Fix up docs and make the common case the default
This commit is contained in:
Stuart Colville
Родитель
674d268cad
Коммит
f3db2381ef
|
|
@ -59,4 +59,4 @@ docker/artifacts/*
|
|||
logs/*
|
||||
supervisord.pid
|
||||
.ipython
|
||||
docker-compose.override.yml
|
||||
docker*.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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче