doc/DEVCONTAINER.md

   1 # Using Development Containers for development and testing
   2
   3 You can set up a development environment for this project using [Development Containers](https://containers.dev/), aka devcontainers.
   4
   5 There are different ways of working with devcontainers. Some are automated and integrated in IDE applications, while others are more manual and require CLI tools. This guide will use [Visual Studio Code](https://code.visualstudio.com) and assumes that it's installed already.
   6
   7 Be aware that the containers will take significant space in your hard drive, in the region of 6GB.
   8
   9 ## Install Git
  10
  11 You will need Git to clone (download) the code repository and push changes. How to install Git will depend on your operating system.
  12
  13 ### Ubuntu 24.04 LTS, Debian 13 (Trixie)
  14
  15 ```bash
  16 sudo apt-get update
  17 sudo apt-get install git-core
  18 ```
  19
  20 ### Fedora
  21
  22 ```bash
  23 sudo dnf install git
  24 ```
  25
  26 ### macOS
  27
  28 For macOS, you will need [Xcode Command Line Tools](https://mac.install.guide/commandlinetools/); macOS 14 (Sonoma) or later; and some familiarity with Unix development via the Terminal.
  29
  30 ### Windows
  31
  32 You can install Git using [WinGet](https://learn.microsoft.com/en-gb/windows/package-manager/winget/):
  33
  34 ```bash
  35 winget install --id Git.Git -e --source winget
  36 ```
  37
  38 Alternatively, see [other install options](https://git-scm.com/install/windows).
  39
  40 ## Install Docker
  41
  42 You will need to install Docker in order to run devcontainers. Again, the methods will depend on your operating system.
  43
  44 In general: if you get an error about not having permission to use Docker, you may need to add your user to the `docker` group. The details vary, but often this is a case of running the following command:
  45
  46 ```bash
  47 sudo usermod --append --group docker $USERNAME
  48 ```
  49
  50 Substitute `$USERNAME` with your actual username in the command above. After that, reboot your computer to ensure that this change takes effect.
  51
  52 ### Windows
  53
  54 1. Use Docker Desktop via [docker.com Download](https://www.docker.com/products/docker-desktop/).
  55
  56 2. You have to enable git symlinks before cloning the repository.
  57    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.
  58
  59 ### Mac
  60
  61 - Use Docker Desktop via [docker.com Download](https://www.docker.com/products/docker-desktop/).
  62 - Or [Homebrew](https://formulae.brew.sh/cask/docker).
  63
  64 ### Linux
  65
  66 Use [Docker Engine](https://docs.docker.com/engine/install/ubuntu/) with the [docker-compose-plugin](https://docs.docker.com/compose/install/linux/)
  67
  68 ## Clone the repository
  69
  70 The repository is reasonably large (~560MB) and it's unlikely that you'll need the full history. Therefore you can probably do with a shallow clone (~100MB):
  71 ```bash
  72 git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git
  73 ```
  74
  75 If you want to add in the full history later on, perhaps to run `git blame` or `git log`, run `git fetch --unshallow`.
  76
  77 > [!TIP]
  78 > To download the full history from the start, run:
  79 > ```bash
  80 > git clone https://github.com/openstreetmap/openstreetmap-website.git
  81 > ```
  82
  83 ## Install Dev Containers extension
  84
  85 Start by opening the project with VS Code. Within it, you will need to install the extension _Dev Containers_, which can be done from the _Extensions_ section, reachable via the sidebar icons. Or VS Code may show a popup recommending this extension, with a button to install it directly.
  86
  87 ![VS Code: panel to install extensions](./assets/vscode-devcontainers-extension.png)
  88
  89 ## Open the project in a container
  90
  91 If everything is correct, this should make a few new commands available to you within VS Code. Find and run the command "Dev Containers: Reopen in Container".
  92
  93 ![VS Code: command to open in a devcontainer](./assets/vscode-dev-reopen.png)
  94
  95 The first time you do this, it will go into a bit of a process. It will create the devcontainer, pull the Docker images, install the dependencies, etc. Go drink some water while this runs.
  96
  97 ![VS Code: notification that VS Code is connecting to the Dev Container](./assets/vscode-connecting-to-devcontainer.png)
  98
  99 Eventually this will present you with a development environment ready to go. In subsequent occasions this should be much faster.
 100
 101 ## Done!
 102
 103 If everything went well, you are done! For example, now you can open a shell in this environment using the VS Studio command "Create New Terminal (With Profile)":
 104
 105 ![VS Code: command to open a terminal](./assets/vscode-create-terminal.png)
 106
 107 From this terminal, you can run the test suite with `bundle exec rails test:all`:
 108
 109 ![Running the test suite in the terminal](./assets/vscode-rails-test-all.png)
 110
 111 Hopefully it should be all green? 🤞 You can also start a development server with `bundle exec rails s`:
 112
 113 ![Running the dev server in the terminal](./assets/vscode-rails-server.png)
 114
 115 It will take a moment to start, after which you will be able to take a browser to http://localhost:3000 and visit your own local version of the site.
 116
 117 > [!NOTE]
 118 > 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.
 119
 120 ## What's next?
 121
 122 🎉 **Congratulations!** You have successfully installed the OpenStreetMap website.
 123
 124 **Next steps:**
 125 * **Configuration:** See [CONFIGURE.md](CONFIGURE.md) for populating the database with data, creating users, setting up OAuth, and other configuration tasks.
 126 * **Contributing:** Check out [CONTRIBUTING.md](../CONTRIBUTING.md) for coding style guidelines, testing procedures, and how to submit your contributions.
 127
 128 Any terminal commands must be run like above, in the terminal provided by VS Code to run within the devcontainer.
 129
 130 ## Other tools
 131
 132 VS Code is not the only way to work with devcontainers. Other options include:
 133
 134 - [RubyMine](https://www.jetbrains.com/help/ruby/start-dev-container-inside-ide.html): another popular environment to work with Ruby.
 135 - [DevPod](https://devpod.sh): a CLI tool to work with devcontainers.
 136 - [VSCodium](https://vscodium.com): a Free/Libre alternative to VS Code.
 137 - [GitHub Codespaces](https://github.com/codespaces): GitHub's hosted IDE.
 138
 139 ## Troubleshooting
 140
 141 ### `‘ruby’: No such file or directory`
 142
 143 In some cases Ruby may not install correctly. If you see this message, run these two commands:
 144
 145 ```
 146 mise install
 147 bundle install
 148 ```
 149
 150 This has been observed particularly when using RubyMine.