doc/DOCKER.md

   1 # Using Docker and Docker Compose for Development and Testing
   2
   3 These instructions are designed for setting up `openstreetmap-website` for development and testing using [Docker](https://www.docker.com/). This 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.
   4
   5 ## Install Docker
   6
   7 ### Windows
   8
   9 1. Use Docker Desktop via [docker.com Download](https://www.docker.com/products/docker-desktop/).
  10
  11 2. You have to enable git symlinks before cloning the repository.
  12    This repository uses symbolic links that are not enabled by default on Windows git. To enable them, [turn on Developer Mode](https://windowsreport.com/windows-11-developer-mode/) on Windows and run `git config --global core.symlinks true` to enable symlinks in Git. See [this StackOverflow question](https://stackoverflow.com/questions/5917249/git-symbolic-links-in-windows) for more information.
  13
  14 ### Mac
  15
  16 - Use Docker Desktop via [docker.com Download](https://www.docker.com/products/docker-desktop/).
  17 - Or [Homebrew](https://formulae.brew.sh/cask/docker).
  18
  19 ### Linux
  20
  21 Use [Docker Engine](https://docs.docker.com/engine/install/ubuntu/) with the [docker-compose-plugin](https://docs.docker.com/compose/install/linux/)
  22
  23 ## Clone repository
  24
  25 The first step is to fork/clone the repo to your local machine:
  26
  27 ```bash
  28 git clone https://github.com/openstreetmap/openstreetmap-website.git
  29 ```
  30
  31 Now change working directory to the `openstreetmap-website`:
  32
  33 ```bash
  34 cd openstreetmap-website
  35 ```
  36
  37 ## Initial Setup
  38
  39 ### Storage
  40
  41 ```bash
  42 cp config/example.storage.yml config/storage.yml
  43 ```
  44
  45 ### Database
  46
  47 ```bash
  48 cp config/docker.database.yml config/database.yml
  49 ```
  50
  51 ## Prepare local settings file
  52
  53 This is a workaround. [See issues/2185 for details](https://github.com/openstreetmap/openstreetmap-website/issues/2185#issuecomment-508676026).
  54
  55 ```bash
  56 touch config/settings.local.yml
  57 ```
  58
  59 **Windows users:** `touch` is not an available command in Windows so just create a `settings.local.yml` file in the `config` directory, or if you have WSL you can run `wsl touch config/settings.local.yml`.
  60
  61 ## Installation
  62
  63 To build local Docker images run from the root directory of the repository:
  64
  65 ```bash
  66 docker compose build
  67 ```
  68
  69 If this is your first time running or you have removed cache this will take some time to complete. Once the Docker images have finished building you can launch the images as containers.
  70
  71 To launch the app run:
  72
  73 ```bash
  74 docker compose up -d
  75 ```
  76
  77 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:
  78
  79 - You can tail logs of a running container with a command like this: `docker compose logs -f web` or `docker compose logs -f db`.
  80 - 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`.
  81
  82 ## Running commands
  83
  84 At this point, the Docker container can be used although there are a couple of steps missing to complete the install.
  85
  86 From now on, any commands should be run within the container. To do this, first you need to open a shell within it:
  87
  88 ```bash
  89 docker compose run --rm web bash
  90 ```
  91
  92 This will open a shell where you can enter commands. These commands will run within the context of the container, without affecting your own machine outside your working directory.
  93
  94 > [!IMPORTANT]
  95 > Unless otherwise stated, make sure that you are in this shell when following any other instructions.
  96
  97 ### Create the databases
  98
  99 To create all databases and set up all databases, run:
 100
 101 ```bash
 102 bundle exec rails db:create
 103 ```
 104
 105 ## Validate Your Installation
 106
 107 Hopefully that's it? Let's check that things are working properly.
 108
 109 ### Run the tests
 110
 111 Run the test suite:
 112
 113 ```bash
 114 bundle exec rails test:all
 115 ```
 116
 117 This test will take a few minutes, reporting tests run, assertions, and any errors. If you receive no errors, then your installation was successful. On occasion some tests may fail randomly and will pass if run again. We are working towards avoiding this, but it can still happen.
 118
 119 > [!NOTE]
 120 > The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored.
 121
 122 ### Start the development server
 123
 124 Rails comes with a built-in webserver, so that you can test on your own machine without needing a server. Run:
 125
 126 ```bash
 127 bundle exec rails server
 128 ```
 129
 130 You can now view the site in your favourite web browser at [http://localhost:3000/](http://localhost:3000/)
 131
 132 > [!NOTE]
 133 > The OSM map tiles you see aren't created from your local database - they are the production map tiles, served from a separate service over the Internet.
 134
 135 ## What's next?
 136
 137 🎉 **Congratulations!** You have successfully installed the OpenStreetMap website.
 138
 139 **Next steps:**
 140 * **Configuration:** See [CONFIGURE.md](CONFIGURE.md) for populating the database with data, creating users, setting up OAuth, and other configuration tasks.
 141 * **Contributing:** Check out [CONTRIBUTING.md](../CONTRIBUTING.md) for coding style guidelines, testing procedures, and how to submit your contributions.
 142
 143 Don't forget to **run any commands in a shell within the container**, as instructed above under "Running commands".