Skip to content

Plugins on Docker Hub

Jump to bottom
thejonas edited this page Aug 10, 2015 · 14 revisions

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 3000:3000 --name=overview-word-cloud 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: docker ps
  • Read plugin logs. docker logs overview-word-cloud. To show new log messages as they appear, run docker logs -f overview-word-cloud.
  • Shut down a plugin. 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.

Deploying on our AWS account

AWS setup: one-time setup for all containers

  1. Create a VPC named plugins, at 10.10.0.0/16.
  2. Create a subnet named plugins, on VPC plugins at 10.10.10.0/24. Ensure the subnet has a route table with an internet gateway.
  3. Go to AWS web console -> EC2 -> Load Balancers -> Create Load Balancer
  4. Name it plugins and put it in the plugins VPC. (It should not be an "internal load balancer".)
  5. Choose HTTPS (443) to port 80. (This won't point to anything, but we need it to continue.) Choose the plugins subnet.
  6. In Step 2: Assign Security Groups, create a new security group called plugins-load-balancer that allows access to ports 3000-3999 from anywhere.
  7. Upload the *.overviewdocs.com SSL certificate: the private key, public certificate, and certificate chain. Name it STAR.overviewdocs.com. Use the Predefined Security Policy to select a cipher suite.
  8. Leave the Health Check defaults. Don't add any EC2 Instances. Add a tag, Name=plugins.
  9. Create an ECS cluster. aws ecs create-cluster --cluster-name plugins
  10. Create ecsInstanceRole: iAM -> Roles -> Create New Role -> ecsInstanceRole and attach the policy AmazonEC2ContainerServiceforEC2Role.
  11. Create ecsServiceRole: iAM -> Roles -> Create New Role -> ecsServiceRole and attach the policy AmazonEC2ContainerServiceRole.
  12. Launch an instance as specified at http://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_container_instance.html. Use instance type t2.large. Ensure the instance has a public IP. Do chose Advanced Details to set ECS_CLUSTER=plugins as explained in the guide. Choose a 30GB gp2 volume, tag Name=plugins, a new plugins security group that allows access to ports 3000-3999 from plugins-load-balancer. Choose whatever keypair -- we should never need to connect to this instance via SSH.
  13. Register an elastic IP for the load balancer.
  14. Point plugins.overviewdocs.com to the elastic IP.

AWS setup: launching a plugin

  1. Ensure the plugin is registered on Docker Hub under the overview organization.
  2. Clone https://github.com/overview/overview-plugins
  3. Pick a port, by looking in plugins.txt
  4. Run ./register.sh [plugin name] [port] [memory]
  5. Commit and push
  6. Run `./deploy.sh [plugin name]
Clone this wiki locally