Plugins on Docker Hub

We publish official Overview plugins on Docker Hub. That means end users (and we) can install all plugins exactly the same way.

Using an Overview plugin from Docker Hub

As an end user, how do you run a plugin? We'll assume you're running Overview on your own machine. To make that happen, see Setting up a development environment.

Is Overview running on your machine now? Great. Here's what you do.

1. Run Overview. It should be running at http://localhost:9000.
2. Install Docker. The official Docker website has complete installation instructions: https://docs.docker.com/installation/.
3. Find a project. The full list is at https://registry.hub.docker.com/repos/overview/. A project might be named, say, overview/overview-word-cloud.
4. Open a command prompt. The Docker instructions tell you how to do it on your operating system.
5. Run the project with a single command: docker run -d -p --name=overview-word-cloud 3000:3000 overview/overview-word-cloud.
6. Figure out Docker's IP address. On Linux, you can use localhost. On Mac and Windows, it's almost certainly 192.168.59.103.
7. Figure out your IP address -- anything that doesn't look like localhost, 127.x.x.x or ::1. Use 172.17.42.1 on Linux and 192.168.59.3 on Mac and Windows.
8. Browse to Overview using your IP address (not localhost). For instance, http://172.17.42.1:9000` (Linux) or http://192.168.59.3:9000 (Mac and Windows). If that doesn't work, check our troubleshooting section.
9. Use the plugin. Open a document set in Overview. Click on Add view -> Custom…. Enter any name, and choose http://[Docker IP]:3000. (That's http://localhost:3000 on Linux, http://192.168.59.103:3000 on Mac and Windows.) Click through the SSL warning, then choose Create Visualization.
10. (optional) Register the plugin. If you plan on using this visualization a lot, you can set up a shortcut for it. From Overview's main page, go to Admin -> Plugins. Enter a name and description, and use the Docker URL from the previous step. (That's http://localhost:3000 on Linux, http://192.168.59.103:3000 on Mac and Windows.)
11. Run more plugins! You can run lots and lots of plugins at the same time. Just repeat the "Find a project" and "Run the project" commands as above. But instead of -p 3000:3000, use -p 3001:3000. When you use your plugin in Overview, use :3001 instead of :3000 in the plugin URL. (With plugin number three, use 3002:3000 and :3002. Et cetera.)

Whew! Now, here are some commands that will prove useful:

• List running plugins: run docker ps
• Read plugin logs. run docker logs overview-word-cloud. To show new log messages as they appear, run docker logs -f overview-word-cloud.
• Shut down a plugin. run docker rm -f overview-word-cloud

Troubleshooting

My browser shows Connection refused when I try to open Overview at http://172.17.42.1:9000 (Linux) or http://192.168.59.3:9000 (Mac/Windows).

Check that you can see Overview at http://localhost:9000. If you can't, Overview isn't set up properly; go to Setting up a development environment.

If localhost works and the other address we supplied doesn't, that's because we were lazy: we just guessed what the IP address would be, and we guessed wrong. You can find an address like so:

• Linux: Find the address by running ip -o addr show docker0 | cut -d'/' -f1.
• Mac OS: Find the address by running ifconfig | grep 'Link\|inet'. Try out the "inet addr" values whose names start with vboxnet first; otherwise, any other address (except 127.0.0.1) will work.
• Windows: Run ipconfig. If you can spot a vboxnet in the noise, try out the associated address; but really, any address (except 127.0.0.1) will work.

The above-mentioned commands might list several IP addresses; there's no harm in trying them all. Type each into your browser bar: http://[ip address]:9000. Use whichever address works.

Overview says http://[ip address]:3000/metadata responded with status code 0

First, check that the plugin is running. You should see it when you run docker ps.

If the plugin isn't running, then try running the docker run command from above again. If it still doesn't work, the plugin code might be faulty. Please contact us ... and maybe try out a second plugin, to be sure.

If the plugin is running, then please excuse our laziness: we guessed at an IP address, and we were wrong. Find Docker's IP address like so:

• Linux: Find the address by running ip -o addr show docker0 | cut -d'/' -f1.
• Mac/Windows: Find the address by running boot2docker ip.

Plug that IP address into Overview: that is, http://[ip address]:3000.

Developers: publishing an Overview plugin on Docker Hub

Docker Hub automatically rebuilds each plugin we've registered, so you need only follow these steps once:

1. Add a Dockerfile to the project. Also add a .dockerignore, which should probably be very similar to .gitignore. The .dockerignore can save a lot of time when building images.
2. Run docker build -t test-app . to ensure the Dockerfile is correct.
3. Run docker run -t -i -p 3000:3000 --name=test-app test-app (or pick a different port: say, 3005:3000) and ensure you can use the plugin correctly from within Overview. Make sure you're using the correct IP addresses and ports, as specified above. When you're done testing, kill it with docker rm -f test-app.
4. Commit the Dockerfile and push it to GitHub.
5. Register the plugin: From https://registry.hub.docker.com/repos/ go to Add Repository -> Automated Build. Choose GitHub (you're sharing private repositories, right?) and then Select the repository you want. Change the Namespace to overview, and click Create Repository.
6. Wait until the build completes.
7. Rejoice.