INSTALL.md

   1 # Installation
   2
   3 These instructions are designed for setting up `openstreetmap-website` development environment. If you want to deploy the software for your own project, then see the [Production Deployment Notes](#production-deployment-notes).
   4
   5 ## Installation Options
   6
   7 There is more than one way to set up a development environment.
   8
   9 ### Containerized Installation
  10
  11 We offer containerized environments with Docker which may avoid installation difficulties:
  12
  13 - To use Docker manually, see [DOCKER](DOCKER.md).
  14 - To use Docker via [Development Containers](https://containers.dev) (devcontainers), see [DEVCONTAINER.md](DEVCONTAINER.md).
  15
  16 ### Manual Installation
  17
  18 Install dependencies directly on your machine (traditional approach, covered in this guide). This gives you the most control and is often preferred by experienced developers on Linux systems.
  19
  20 > [!WARNING]
  21 > **Windows Note:** We don't recommend using this approach on Windows, as some Ruby gems may not be supported. If you are using Windows, we recommend a containerized setup as mentioned above.
  22
  23 ## Manual Installation Guide
  24
  25 These instructions are based on Ubuntu 24.04 LTS, though the OSMF servers are currently running Debian 12. The instructions also work, with only minor amendments, for all other current Ubuntu releases, Fedora and macOS.
  26
  27 ### Prerequisites
  28
  29 Many of the dependencies are managed through the standard Ruby on Rails mechanisms - i.e. Ruby gems specified in the Gemfile and installed using Bundler. Some system packages are also required before you can get the various gems installed.
  30
  31 **Minimum requirements:**
  32 * Ruby 3.2+
  33 * PostgreSQL 13+
  34 * Bundler (see note below about [developer Ruby setup](#ruby-version-manager-optional))
  35 * JavaScript Runtime
  36
  37 ### Step 1: Install System Dependencies
  38
  39 #### Ubuntu 24.04 LTS
  40
  41 ```bash
  42 sudo apt-get update
  43 sudo apt-get install ruby ruby-dev ruby-bundler \
  44                      libvips-dev libxml2-dev libxslt1-dev \
  45                      nodejs build-essential git-core \
  46                      postgresql postgresql-contrib libpq-dev \
  47                      libsasl2-dev libffi-dev libgd-dev \
  48                      libarchive-dev libyaml-dev libbz2-dev npm
  49 sudo npm install --global yarn
  50 ```
  51
  52 > [!TIP]
  53 > On Ubuntu 24.04, you may need to start PostgreSQL:
  54 >
  55 > ```bash
  56 > sudo systemctl start postgresql.service
  57 > ```
  58
  59 #### Fedora
  60
  61 ```bash
  62 sudo dnf install ruby ruby-devel rubygem-rdoc rubygem-bundler \
  63                  rubygems libxml2-devel nodejs gcc gcc-c++ git \
  64                  postgresql postgresql-server \
  65                  postgresql-contrib libpq-devel \
  66                  perl-podlators libffi-devel gd-devel \
  67                  libarchive-devel libyaml-devel bzip2-devel \
  68                  nodejs-yarn vips-devel
  69 ```
  70
  71 On Fedora, if you didn't already have PostgreSQL installed then create a PostgreSQL instance and start the server:
  72
  73 ```bash
  74 sudo postgresql-setup initdb
  75 sudo systemctl start postgresql.service
  76 ```
  77
  78 Optionally set PostgreSQL to start on boot:
  79
  80 ```bash
  81 sudo systemctl enable postgresql.service
  82 ```
  83
  84 #### macOS
  85
  86 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.
  87
  88 **Installing PostgreSQL:**
  89
  90 * Install Postgres.app from https://postgresapp.com/
  91 * Make sure that you've initialized and started Postgresql from the app (there should be a little elephant icon in your systray).
  92 * Add PostgreSQL to your path, by editing your profile:
  93
  94 ```bash
  95 nano ~/.profile
  96 ```
  97
  98 and adding:
  99
 100 ```bash
 101 export PATH=/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH
 102 ```
 103
 104 After this, you may need to start a new shell window, or source the profile again by running `. ~/.profile`.
 105
 106 **Installing other dependencies:**
 107
 108 * Install Homebrew from https://brew.sh/
 109 * Install system dependencies, including Ruby:
 110 ```bash
 111 brew install ruby libxml2 gd yarn pngcrush optipng \
 112              pngquant jhead jpegoptim gifsicle svgo \
 113              advancecomp vips
 114 ```
 115 * Install Bundler: `gem install bundler` (you might need to `sudo gem install bundler` if you get an error about permissions - or see note below about [developer Ruby setup](#ruby-version-manager-optional))
 116
 117 You will need to tell `bundler` that `libxml2` is installed in a Homebrew location. If it uses the system-installed one then you will get errors installing the `libxml-ruby` gem later on.
 118
 119 ```bash
 120 bundle config build.libxml-ruby --with-xml2-config=/usr/local/opt/libxml2/bin/xml2-config
 121 ```
 122
 123 If you want to run the tests, you need `geckodriver` as well:
 124
 125 ```bash
 126 brew install geckodriver
 127 ```
 128
 129 > [!NOTE]
 130 > OS X does not have a /home directory by default, so if you are using the GPX functions, you will need to change the directories specified in config/application.yml.
 131
 132 ### Step 2: Clone the Repository
 133
 134 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):
 135 ```bash
 136 git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git
 137 ```
 138
 139 If you want to add in the full history later on, perhaps to run `git blame` or `git log`, run `git fetch --unshallow`.
 140
 141 > [!TIP]
 142 > To download the full history from the start, run:
 143 > ```bash
 144 > git clone https://github.com/openstreetmap/openstreetmap-website.git
 145 > ```
 146
 147 ### Step 3: Install Application Dependencies
 148
 149 #### Ruby gems
 150
 151 We use [Bundler](https://bundler.io/) to manage the rubygems required for the project.
 152
 153 ```bash
 154 cd openstreetmap-website
 155 bundle install
 156 ```
 157
 158 #### Node.js modules
 159
 160 We use [Yarn](https://yarnpkg.com/) to manage the Node.js modules required for the project.
 161
 162 ```bash
 163 bundle exec bin/yarn install
 164 ```
 165
 166 ### Step 4: Prepare Configuration Files
 167
 168 #### Local settings file
 169
 170 > [!NOTE]
 171 > This is a workaround. [See issues/2185 for details](https://github.com/openstreetmap/openstreetmap-website/issues/2185#issuecomment-508676026).
 172
 173 ```bash
 174 touch config/settings.local.yml
 175 ```
 176
 177 #### Storage setup
 178
 179 `openstreetmap-website` needs to be configured with an object storage facility - for development and testing purposes you can use the example configuration:
 180
 181 ```bash
 182 cp config/example.storage.yml config/storage.yml
 183 ```
 184
 185 ### Step 5: Database Setup
 186
 187 `openstreetmap-website` uses three databases - one for development, one for testing, and one for production. The database-specific configuration options are stored in `config/database.yml`, which we need to create from the example template.
 188
 189 ```bash
 190 cp config/example.database.yml config/database.yml
 191 ```
 192
 193 > [!IMPORTANT]
 194 > PostgreSQL is configured to, by default, accept local connections without requiring a username or password. This is fine for development. If you wish to set up your database differently, then you should change the values found in the `config/database.yml` file, and amend the instructions below as appropriate.
 195
 196 #### PostgreSQL account setup
 197
 198 We need to create a PostgreSQL role (i.e. user account) for your current user, and it needs to be a superuser so that we can create more databases.
 199
 200 ```bash
 201 sudo -u postgres -i
 202 createuser -s <username>
 203 exit
 204 ```
 205
 206 #### Create the databases
 207
 208 To create the three databases - for development, testing and production - run:
 209
 210 ```bash
 211 bundle exec rails db:create
 212 ```
 213
 214 #### Database structure
 215
 216 To create all the tables, indexes and constraints, run:
 217
 218 ```bash
 219 bundle exec rails db:migrate
 220 ```
 221
 222 ## Validate Your Installation
 223
 224 ### Running the tests
 225
 226 To ensure that everything is set up properly, you should now run:
 227
 228 ```bash
 229 bundle exec rails test:all
 230 ```
 231
 232 This test will take a few minutes, reporting tests run, assertions, and any errors. If you receive no errors, then your installation is successful.
 233
 234 > [!NOTE]
 235 > The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored.
 236
 237 ### Starting the server
 238
 239 Rails comes with a built-in webserver, so that you can test on your own machine without needing a server. Run
 240
 241 ```bash
 242 bundle exec rails server
 243 ```
 244
 245 You can now view the site in your favourite web-browser at [http://localhost:3000/](http://localhost:3000/)
 246
 247 > [!NOTE]
 248 > 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.
 249
 250 ## What's Next?
 251
 252 🎉 **Congratulations!** You have successfully installed the OpenStreetMap website.
 253
 254 **Next steps:**
 255 * **Configuration:** See [CONFIGURE.md](CONFIGURE.md) for populating the database with data, creating users, setting up OAuth, and other configuration tasks.
 256 * **Contributing:** Check out [CONTRIBUTING.md](CONTRIBUTING.md) for coding style guidelines, testing procedures, and how to submit your contributions.
 257
 258 ## Ruby Version Manager (Optional)
 259
 260 For simplicity, this document explains how to install all the website dependencies as "system" dependencies. While this can be simpler and faster, you might want more control over the process or the ability to install multiple different versions of Ruby alongside each other.
 261
 262 Several tools exist that allow managing multiple different Ruby versions on the same computer. They also provide the additional advantage that the installs are all in your home directory, so you don't need administrator permissions. These tools are typically known as "version managers".
 263
 264 This section shows how to install Ruby and Bundler with [`rbenv`](https://github.com/rbenv/rbenv), which is one of these tools. If you choose to install Ruby and Bundler via `rbenv`, then you do not need to install the system libraries for Ruby:
 265
 266 * For Ubuntu, you do not need to install the following packages: `ruby ruby-dev ruby-bundler`,
 267 * For Fedora, you do not need to install the following packages: `ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems`
 268 * For macOS, you do not need to `brew install ruby`
 269
 270 > [!IMPORTANT]
 271 > On macOS, make sure you've installed a version of Ruby using `rbenv` before running `gem install bundler`!
 272
 273 After installing a version of Ruby with `rbenv` (the latest stable version is a good place to start), you will need to make that the default. From inside the `openstreetmap-website` directory, run:
 274
 275 ```bash
 276 rbenv local $VERSION
 277 ```
 278
 279 Where `$VERSION` is the version you installed. You can see a list of available versions by running `rbenv versions`. Then install bundler:
 280
 281 ```bash
 282 gem install bundler
 283 ```
 284
 285 You should now be able to proceed with the rest of the installation. If you're on macOS, make sure you set up the [config override for the libxml2 location](#macos-click-to-expand) _after_ installing bundler.
 286
 287 ## Production Deployment Notes
 288
 289 > [!WARNING]
 290 > Production deployment requires careful configuration and is significantly different from development setup.
 291
 292 If you want to deploy `openstreetmap-website` for production use, you'll need to make a few changes:
 293
 294 > [!IMPORTANT]
 295 > It's not recommended to use `rails server` in production. Our recommended approach is to use [Phusion Passenger](https://www.phusionpassenger.com/). Instructions are available for [setting it up with most web servers](https://www.phusionpassenger.com/documentation_and_support#documentation).
 296
 297 * Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.
 298
 299 > [!TIP]
 300 > The included version of the map call is quite slow and eats a lot of memory. You should consider using [CGIMap](https://github.com/zerebubuth/openstreetmap-cgimap) instead.
 301
 302 * Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production bundle exec i18n export; bundle exec rails assets:precompile`
 303 * Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.