From 7149fb72f685d4950835d25c045ce96b13ef496f Mon Sep 17 00:00:00 2001 From: Matthew Somerville Date: Thu, 27 Sep 2018 17:16:44 +0100 Subject: [Docs] Initial documentation for Docker installations This adds details of our Docker images and the example Docker Compose environment, including notes on how to use this with a cobrand and how to customise the database configuration. --- .gitignore | 1 + CHANGELOG.md | 1 + docs/_layouts/page.html | 3 +- docs/customising/boundaries.md | 2 +- docs/glossary.md | 4 +- docs/how-it-works.md | 5 +-- docs/install/ami.md | 2 +- docs/install/docker.md | 91 +++++++++++++++++++++++++++++++++++++++++ docs/install/index.md | 8 ++-- docs/install/install-script.md | 2 +- docs/install/manual-install.md | 2 +- docs/install/troubleshooting.md | 2 +- docs/install/vagrant.md | 2 +- 13 files changed, 108 insertions(+), 17 deletions(-) create mode 100644 docs/install/docker.md diff --git a/.gitignore b/.gitignore index 84a1d776a..9c6297b3d 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,7 @@ blib/ inc/ _Inline/ *.pyc +docker-compose.override.yml # International /fixmystreet-international diff --git a/CHANGELOG.md b/CHANGELOG.md index d178975b1..10e0776b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ might need applying to a cobrand. - Move away from FastCGI in sample conf/sysvinit config. - Customised Vagrant box available, with an override option. + - Add Dockerfile and example Docker Compose setup. * v2.4 (6th September 2018) - Security diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html index 79097b5a9..11ec206ec 100644 --- a/docs/_layouts/page.html +++ b/docs/_layouts/page.html @@ -56,9 +56,10 @@ layout: default

  • Installing

    • diff --git a/docs/customising/boundaries.md b/docs/customising/boundaries.md index d48a472aa..fc1873e9e 100644 --- a/docs/customising/boundaries.md +++ b/docs/customising/boundaries.md @@ -129,7 +129,7 @@ to a very specific area.

    - This is the default setup of a new FixMyStreet installation (if you used the + This is the default setup of a new FixMyStreet installation (if you used e.g. the installation script or the AMI install).

    diff --git a/docs/glossary.md b/docs/glossary.md index 47728c7b5..58397345b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -354,9 +354,9 @@ technical information, see it would contain your own private config settings, such as your database password). Instead, there is an example file, cong/general.yml-example you can - copy and edit. If you install using the + copy and edit. If you install using an automated method such as the installation script - or the AMI, this file will + or Docker, this file will automatically be created for you.

    diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 778563710..ea313de6b 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -68,10 +68,7 @@ If you want to get FixMyStreet up and running, this is what you need to do:

    2. Install the software

    - +

    See the various ways to install the software.

    3. Get the data for the areas you want to cover

    diff --git a/docs/install/ami.md b/docs/install/ami.md index 783c23727..5f6df3af4 100644 --- a/docs/install/ami.md +++ b/docs/install/ami.md @@ -12,7 +12,7 @@ title: AMI for EC2 EC2 instance.

    -Note that this is just one of [four ways to install FixMyStreet]({{ "/install/" | relative_url }}). +Note that this is just one of [many ways to install FixMyStreet]({{ "/install/" | relative_url }}). ## Installing on Amazon's Web Services diff --git a/docs/install/docker.md b/docs/install/docker.md new file mode 100644 index 000000000..3c716a5da --- /dev/null +++ b/docs/install/docker.md @@ -0,0 +1,91 @@ +--- +layout: page +title: Docker +--- + +# FixMyStreet with Docker + +

    + You can use Docker and Docker Compose to get up and running quickly + with FixMyStreet. +

    + +This is just one of [many ways to install FixMyStreet]({{ "/install/" | relative_url }}). + +## Public images + +As well as providing a `Dockerfile` which you could use as the basis of your own +customised build, we provide public [images on Docker Hub](https://hub.docker.com/u/fixmystreet/) +with a full FixMyStreet installation for each of our tagged releases. + +## Docker Compose + +If you have Docker and Docker Compose installed, then the following should +set up a working FixMyStreet installation, with containers for the application, +database, memcached and webserver: + + docker-compose up + +You can then layer your own [cobrand-specific code](/customising/) +on top, update the configuration, or log in and make changes. + +A superuser is automatically created, with email `superuser@example.org` +and password given in `docker-compose.yml`. + +This basic installation uses the default cobrand, with a +(deliberately) rather garish colour scheme. + +## Adding your own cobrand + +If you want to map your own cobrand data into the Docker container, have a +repository/directory that contains the following (all items optional): + + my-cobrand-repo/ + templates/web/(cobrand)/ + templates/email/(cobrand)/ + perllib/FixMyStreet/Cobrand/(CoBrand.pm) + web/cobrands/(cobrand)/ + +Create a docker-compose.override.yml file containing: + + version: '3' + + services: + fixmystreet: + volumes: + - /path/to/your/general.yml:/var/www/fixmystreet/fixmystreet/conf/general.yml + - /path/to/my-cobrand-repo:/var/www/fixmystreet/cobrand + +Now if you run `docker-compose up` it should automatically include that cobrand +within the running container. + +This is a new facility, so please do feed back your thoughts. + +## Database configuration + +The example Docker Compose environment includes a [slightly customised Postgres container](https://github.com/mysociety/public-builds/tree/master/docker/postgres) +based on [the official image](https://hub.docker.com/_/postgres/) and localised for `en_GB`. + +This will be configured the first time it is started and its data stored in a +Docker volume for persistence. The password for the `postgres` user should be set +in the `POSTGRES_PASSWORD` environment variable and made available to both the +database and application containers; along with the various `FMS_DB_*` environment +variables this will be used to ensure the correct users, permissions and databases +are created when the container starts for the first time. + +### Using an external database + +If you wish to host the database in an external service you can do so by updating +the various `FMS_DB_*` environment variables used by the application container and +in `general.yml`. You should not provide a `POSTGRES_PASSWORD` variable to the +application container in this case. + +The application container will attempt to create the database if it doesn't already exist, so +you can either provide the user with the `CREATEDB` privilege or simply provide +an empty database and the application container will load the schema when it starts +for the first time. + +## Installation complete... now customise + +You should then proceed +to [customise your installation](/customising/). diff --git a/docs/install/index.md b/docs/install/index.md index ebd4a8d7e..22abb263d 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -6,13 +6,13 @@ title: Installing # Installing FixMyStreet Platform

    - There are several options for installing the FixMyStreet platform. Unless - you're confident deploying web applications, we recommend you use the - installation script or the AMI for Amazon EC2. + There are several options for installing the FixMyStreet platform, + including Docker, an AMI for Amazon EC2 or an installation script.

    -## Four ways to install +## Ways to install +* [Use Docker]({{ "/install/docker/" | relative_url }}) * [Use an install script for Debian or Ubuntu servers]({{ "/install/install-script/" | relative_url }}) * [Use a FixMyStreet AMI for Amazon EC2]({{ "/install/ami/" | relative_url }}) * [Vagrant installation]({{ "/install/vagrant/" | relative_url }}), for development diff --git a/docs/install/install-script.md b/docs/install/install-script.md index ba2c2bef8..124434b34 100644 --- a/docs/install/install-script.md +++ b/docs/install/install-script.md @@ -11,7 +11,7 @@ title: Install script FixMyStreet on your server.

    -Note that this is just one of [four ways to install FixMyStreet]({{ "/install/" | relative_url }}). +Note that this is just one of [many ways to install FixMyStreet]({{ "/install/" | relative_url }}). ## Warning: installation changes your setup! diff --git a/docs/install/manual-install.md b/docs/install/manual-install.md index 45522fd4e..8acccdddf 100644 --- a/docs/install/manual-install.md +++ b/docs/install/manual-install.md @@ -11,7 +11,7 @@ title: Installing but the other installation options may be easier:

    Note that this is just one of -[four ways to install FixMyStreet]({{ "/install/" | relative_url }}) +[many ways to install FixMyStreet]({{ "/install/" | relative_url }}) (the other ways are easier!). diff --git a/docs/install/troubleshooting.md b/docs/install/troubleshooting.md index 2b49cb616..b006d18a4 100644 --- a/docs/install/troubleshooting.md +++ b/docs/install/troubleshooting.md @@ -6,7 +6,7 @@ title: Installation troubleshooting # Installation troubleshooting

    - If you've installed FixMyStreet using the + If you've installed FixMyStreet using an automated method such as the installation script or the AMI, you should be good to go. diff --git a/docs/install/vagrant.md b/docs/install/vagrant.md index 0b9cd8812..98f846644 100644 --- a/docs/install/vagrant.md +++ b/docs/install/vagrant.md @@ -12,7 +12,7 @@ We bundle an example Vagrantfile in the repository, which runs the install script for you.

    -Note that this is just one of [four ways to install FixMyStreet]({{ "/install/" | relative_url }}). +Note that this is just one of [many ways to install FixMyStreet]({{ "/install/" | relative_url }}).
    Vagrant is only suitable for use as a -- cgit v1.2.3