diff --git a/.gitignore b/.gitignore index 5e97931598..2a56f9bf92 100644 --- a/.gitignore +++ b/.gitignore @@ -59,4 +59,4 @@ docker/artifacts/* logs/* supervisord.pid .ipython -docker-compose.override.yml +docker*.yml diff --git a/circle.yml b/circle.yml index 564bb3ba2e..9f59f32441 100644 --- a/circle.yml +++ b/circle.yml @@ -14,7 +14,6 @@ test: - gunzip -c geckodriver-v0.9.0-linux64.tar.gz | tar xopf - - chmod +x geckodriver - sudo mv geckodriver /home/ubuntu/bin/wires - - cp docker-compose.override.yml{.tmpl,} - docker-compose pull - docker-compose up -d - sleep 60 diff --git a/docker-compose.override.yml.tmpl b/docker-compose.override.yml similarity index 100% rename from docker-compose.override.yml.tmpl rename to docker-compose.override.yml diff --git a/docs/topics/install/docker.rst b/docs/topics/install/docker.rst index 40457102cf..32ad335c89 100644 --- a/docs/topics/install/docker.rst +++ b/docs/topics/install/docker.rst @@ -4,53 +4,51 @@ Install with Docker .. _install-with-docker: -Want the easiest way to start contributing to AMO? Try our docker-based +Want the easiest way to start contributing to AMO? Try our Docker-based development environment. -First you'll need to install docker_, please check the information for +First you'll need to install Docker_. Please read their docs for the installation steps specific to your operating system. -There are generally two options for running docker depending on the platform +There are two options for running docker depending on the platform you are running. - * Run docker on the host machine directly (recommended if supported) + * Run docker on the host machine directly (recommended) * Run docker-machine which will run docker inside a virtual-machine -Historically mac and windows could only run docker via a vm. That has +Historically Mac and Windows could only run Docker via a vm. That has recently changed with the arrival of docker-for-mac_ and docker-for-windows_. -If your platform can run docker directly either on Linux, with docker-for-mac_ -or docker-for-windows_ then this is the easiest way to install docker with the -most minimal set of moving parts. +If your platform can run Docker directly either on Linux, with docker-for-mac_ +or docker-for-windows_ then this is the easiest way to run ``addons-server``. -If you have problems, due to not meeting the requirenents or you're on windows -and want to keep running docker-machine vms then docker-machine will still -work just fine. See the docs for creating the vm here :ref:`creating-the-docker-vm` +If you have problems, due to not meeting the minimum specifications for +docker-for-windows_ or you'd prefer to keep running docker-machine vms then +docker-machine will still work just fine. See the docs for creating the +vm here :ref:`creating-the-docker-vm` -.. note:: if you're on OSX and already have a working docker-machine setup you - can run that and docker-for-mac (*but not docker-for-windows*) side by side. - The only caveat here is that it's recommended that you keep the versions of - docker on the vm and the host in-sync to ensure compatibility when you switch - between them. +.. note:: + If you're on a Mac and already have a working docker-machine setup you + can run that and docker-for-mac (*but not docker-for-windows*) side by side. + The only caveat is it's recommended that you keep the versions of Docker on + the vm and the host in-sync to ensure compatibility when you switch between + them. Setting up the containers ~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: - docker-toolbox, docker-for-mac and docker-for-windows will install ``docker-compose`` - for you. If you're on linux and you need it, you can install it manually with:: + for you. If you're on Linux and you need it, you can install it manually with:: pip install docker-compose -Next once you have docker up and running follow these steps +Next once you have Docker up and running follow these steps on your host machine:: # Checkout the addons-server sourcecode. git clone git://github.com/mozilla/addons-server.git cd addons-server - # Create the docker-compose.override file with the default ports. - cp docker-compose.override.yml{.tmpl,} # Download the containers docker-compose pull # Can take a while depending on your internet bandwidth. # Start up the containers @@ -59,48 +57,46 @@ on your host machine:: .. note:: - Generally docker requires the code checkout to exist within your home directory so - that docker can mount the source-code into the container. + Docker requires the code checkout to exist within your home directory so + that Docker can mount the source-code into the container. Accessing the web server ~~~~~~~~~~~~~~~~~~~~~~~~ By default our docker-compose config exposes the web-server on port 80 of localhost. -We use olympia.dev as the default hostname to access your container server (e.g. for -Firefox Accounts). To be able access the development environment using http://olympia.dev +We use ``olympia.dev`` as the default hostname to access your container server (e.g. for +Firefox Accounts). To be able access the development environment using ``http://olympia.dev`` you'll need to edit your ``/etc/hosts`` file on your native operating system. For example:: [ip-address] olympia.dev -Typically the ip address is localhost 127.0.0.1 if you're using docker-machine +Typically the IP address is localhost (127.0.0.1) but if you're using docker-machine see :ref:`accessing-the-web-server-docker-machine` for details of how to get the ip of -the docker vm. +the Docker vm. -You can ensure your docker server is configured internally with this host by -setting it in the environment and restarting the docker containers, like this:: +By default we configure `OLYMPIA_SITE_URL` to point to `http://olympia.dev`. + +If you choose a different hostname you'll need to set that environment variable +and restart the Docker containers:: docker-compose stop # only needed if running - export OLYMPIA_SITE_URL=http://olympia.dev + export OLYMPIA_SITE_URL=http://[YOUR_HOSTNAME} docker-compose up -d -.. note:: - The default docker configuration already configures `OLYMPIA_SITE_URL` to - be set to `http://olympia.dev` Running common commands ~~~~~~~~~~~~~~~~~~~~~~~ -Run the tests using ``make``, *outside* of the docker container:: +Run the tests using ``make``, *outside* of the Docker container:: make test -You can run commands inside the docker container by ``ssh``\ing into it using:: - +You can run commands inside the Docker container by ``ssh``\ing into it using:: make shell -Then to run the tests inside the docker container you can run:: +Then to run the tests inside the Docker container you can run:: py.test @@ -135,68 +131,65 @@ migrations:: Gotchas! ~~~~~~~~ -Here's a list of a few of the issues you might face when using docker. +Here's a list of a few of the issues you might face when using Docker. Can't access the web server? ---------------------------- -Check you've created an hosts file entry pointing ``olympia.dev`` to the -relevant ip address. +Check you've created a hosts file entry pointing ``olympia.dev`` to the +relevant IP address. -Also make sure you've copied ``docker-compose.override.yml.tmpl`` to -``docker-compose.override.yml`` to get the default ports. If you haven't -stop the containers with ``docker-compose stop`` copy the file and restart -with ``docker-compose up -d``. - -Another tip is to use ``docker-compose ps`` to check the status of the -containers. If they are failing to start you should be able to tell here. +If containers are failing to start use ``docker-compose ps`` to check their +running status. Another way to find out what's wrong is to run ``docker-compose logs``. Getting "Programming error [table] doesn't exist"? -------------------------------------------------- -Check you've run the ``make initialize_docker`` step. +Make sure you've run the ``make initialize_docker`` step as detailed in +the initial setup instructions. Port collisions (nginx container fails to start) ------------------------------------------------ -Since by default the docker-compose file exposes the port to the nginx -server that sits in front of the web service on port 80 on your host -you might find it fails to start if you're already running a service on -port 80. -This problem will manifest itself by the services failing to start, you'll -be able to see the error like so:: +If you're already running a service on port 80 or 8000 on your host machine, +the ``nginx`` container will fail to start. This is because the +``docker-compose.override.yml`` file tells ``nginx`` to listen on port 80 +and the web service to listen on port 8000 by default. + +This problem will manifest itself by the services failing to start. Here's an +example for the most common case of ``nginx`` not starting due to a collision on +port 80:: ERROR: for nginx Cannot start service nginx:..... ...Error starting userland proxy: Bind for 0.0.0.0:80: unexpected error (Failure EADDRINUSE) ERROR: Encountered errors while bringing up the project. -There's a couple of ways to fix it. Simple one is to find out what's running on -port 80 and stop it:: +You can check what's running on that port by using (sudo is required if +you're looking at port < 1024):: sudo lsof -i :80 -We now specify the ports nginx listens on in the ``docker-compose.override.yml`` -file that you copied from ``docker-compose.override.yml.tmpl`` when going through -the initial setup. The second solution to a port collision is to change the -default port that's bound on the host. +We specify the ports ``nginx`` listens on in the ``docker-compose.override.yml`` +file. If you wish to override the ports you can do so by creating a new ``docker-compose`` +config and starting the containers using that config alongside the default config. -If you need to change the ports you can do so by changing the defaults in -``docker-compose.override.yml``. - -For example if you want to run nginx on your host and still -access the development environment on port 80 you can change -``docker-compose.override.yml`` to this:: +For example if you create a file called ``docker-compose-ports.yml``:: nginx: ports: - 8880:80 -Now the container nginx is listening on 8880 on the host. You can now proxy -to the container nginx from the host nginx with the following nginx config:: +Next you would stop and start the containers with the following:: + + docker-compose stop # only needed if running + docker-compose -f docker-compose.yml -f docker-compose-ports.yml up -d + +Now the container ``nginx`` is listening on 8880 on the host. You can now proxy +to the container ``nginx`` from the host ``nginx`` with the following ``nginx`` config:: server { listen 80; @@ -206,7 +199,6 @@ to the container nginx from the host nginx with the following nginx config:: } } - Persisting changes ------------------ @@ -218,7 +210,7 @@ running container exits. .. note:: If you need to persist any changes to the image, they should be carried out via the ``Dockerfile``. Commits to master will result in the Dockerfile - being rebuilt on the docker hub. + being rebuilt on the Docker hub. Restarting docker-machine vms following a reboot ------------------------------------------------ @@ -247,7 +239,7 @@ such as this to build a new image:: After you test your new image, commit to master and the image will be published to Docker Hub for other developers to use after they pull image changes. -.. _docker: https://docs.docker.com/installation/#installation +.. _Docker: https://docs.docker.com/installation/#installation .. _docker-toolbox: https://www.docker.com/toolbox .. _docker-for-windows: https://docs.docker.com/engine/installation/windows/#/docker-for-windows .. _docker-for-mac: https://docs.docker.com/engine/installation/mac/#/docker-for-mac