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](./docs/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](./docs/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](./docs/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](./docs/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](./docs/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](./docs/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 ## Other useful configuration
 118
 119 See [`CONFIGURE.md`](CONFIGURE.md) for information on how to manage users and enable OAuth for iD, JOSM etc.
 120
 121 ## Other tools
 122
 123 VS Code is not the only way to work with devcontainers. Other options include:
 124
 125 - [RubyMine](https://www.jetbrains.com/help/ruby/start-dev-container-inside-ide.html): another popular environment to work with Ruby.
 126 - [DevPod](https://devpod.sh): a CLI tool to work with devcontainers.
 127 - [VSCodium](https://vscodium.com): a Free/Libre alternative to VS Code.
 128 - [GitHub Codespaces](https://github.com/codespaces): GitHub's hosted IDE.
 129
 130 ## Troubleshooting
 131
 132 ### `‘ruby’: No such file or directory`
 133
 134 In some cases Ruby may not install correctly. If you see this message, run these two commands:
 135
 136 ```
 137 mise install
 138 bundle install
 139 ```
 140
 141 This has been observed particularly when using RubyMine.