From 2eb8e76fd3a2ea23782f874eac51bab8b3569ff9 Mon Sep 17 00:00:00 2001 From: Jamie Alessio Date: Tue, 22 Oct 2019 19:48:39 +0000 Subject: [PATCH] Add Docker README and Makefile for helper commands --- DOCKER.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 22 +++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 DOCKER.md create mode 100644 Makefile diff --git a/DOCKER.md b/DOCKER.md new file mode 100644 index 000000000..74e5f57b6 --- /dev/null +++ b/DOCKER.md @@ -0,0 +1,97 @@ +# Using Docker and Docker Compose to run OpenStreetMap + +Using [Docker](https://www.docker.com/) will allow you to install the OpenStreetMap application and all its dependencies in Docker images and then run them in containers, almost with a single command. You will need to install Docker and Docker Compose on your development machine: + +- [Install Docker](https://docs.docker.com/install/) +- [Install Docker Compose](https://docs.docker.com/compose/install/) + +These instructions gloss over the precise details of the dependencies and their configuration but these can be found in full detail at [INSTALL.md](INSTALL.md). + +The first step is to fork/clone the repo to your local machine. The repository is reasonably large (~150MB) and it's unlikely that you need the full history. If you are happy to wait for it all to download, run: + + git clone https://github.com/openstreetmap/openstreetmap-website.git + +To clone only the most recent version (~23MB), instead use a 'shallow clone': + + git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git + +Now change working directory to the `openstreetmap-website`: + + cd openstreetmap-website + +### Storage setup + + cp config/example.storage.yml config/storage.yml + +### Database + + cp config/docker.database.yml config/database.yml + +### App configuration + + cp config/settings.yml config/settings.local.yml + +### Installation + +In the root directory run: + + docker-compose build + +Now if this is your first time running or you have removed cache this will take some time to complete. So grab tea/coffee and sit tight. Once the Docker images have finished building you can launch the images as containers. + +To launch the app run: + + docker-compose up -d + +This will launch one Docker container for each 'service' specified in `docker-compose.yml` and run them in the background. There are two options for inspecting the logs of these running containers: + +- You can tail logs of a running container with a command like this: `docker-compose logs -f web` or `docker-compose logs -f db`. +- Instead of running the containers in the background with the `-d` flag, you can launch the containers in the foreground with `docker-compose up`. The downside of this is that the logs of all the 'services' defined in `docker-compose.yml` will be intermingled. If you don't want this you can mix and match - for example, you can run the database in background with `docker-compose up -d db` and then run the Rails app in the foreground via `docker-compose up web`. + +### Migrations + +While the `db' service is running, open another terminal windows and run: + + docker-compose run --rm web rake db:migrate + +### Node.js modules + +We use Yarn to manage the Node.js modules required for the project: + + docker-compose run --rm web rake yarn:install + +Once these are complete you should be able to visit the app at http://localhost:3000 + +If localhost does not work, you can use the IP address of the docker-machine. + +### Tests + + docker-compose run --rm web rake test:db + +### Bash + +If you want to get into a web container and run specific commands you can fire up a throwaway container to run bash in via: + + docker-compose run --rm web bash + +Alternatively, if you want to use the already-running `web` container then you can `exec` into it via: + + docker-compose exec web bash + +Similarly, if you want to `exec` in the db container use: + + docker-compose exec db bash + +### Populating the database + +This installation comes with no geographic data loaded. You can either create new data using one of the editors (Potlatch 2, iD, JOSM etc) or by loading an OSM extract. + +After installing but before creating any users or data, import an extract with [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and the `--write-apidb` task. The `web` container comes with `osmosis` pre-installed. So to populate data with a `.osm.pbf` use the following command: + + docker-compose run --rm web osmosis \ + --read-pbf /path/to/file.osm.pbf \ + --write-apidb \ + host="db" \ + database="openstreetmap" \ + user="openstreetmap" \ + validateSchemaVersion="no" diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..d2939d4e4 --- /dev/null +++ b/Makefile @@ -0,0 +1,22 @@ +docker-build: + docker-compose build + +docker-up: + docker-compose up -d + +docker-db-migrate: + docker-compose run --rm web rake db:migrate + +docker-test: + docker-compose run --rm web rake test:db + +docker-populate-db: + wget https://download.geofabrik.de/north-america/us/district-of-columbia-latest.osm.pbf + docker-compose run --rm web osmosis \ + -verbose \ + --read-pbf district-of-columbia-latest.osm.pbf \ + --write-apidb \ + host="db" \ + database="openstreetmap" \ + user="openstreetmap" \ + validateSchemaVersion="no" -- 2.43.2