INSTALL.md

   1 # Installation
   2
   3 These instructions are designed for setting up `openstreetmap-website` development enviroment. 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 You can setup development enviroment by:
   8
   9 ### Containerized Installation
  10
  11 These options provide consistent development environments and may avoid installation difficulties:
  12
  13 * **🐳 Docker** - Uses containerization. See [DOCKER.md](DOCKER.md) for complete instructions.
  14 * **📦 Vagrant** - Installs in a virtual machine. See [VAGRANT.md](VAGRANT.md) for complete instructions.
  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 ---
  21
  22 **Platform Support:** 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.
  23
  24 > [!WARNING]
  25 > **Windows Note:** We don't recommend using this approach for development and deployment on Windows. Some Ruby gems may not be supported. If you are using Windows, we recommend containerized setup using [Docker](DOCKER.md)(preferred) or [Vagrant](VAGRANT.md).
  26
  27 ## Manual Installation Guide
  28
  29 ### Prerequisites
  30
  31 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. However, there are some packages required before you can get the various gems installed.
  32
  33 **Minimum requirements:**
  34 * Ruby 3.2+
  35 * PostgreSQL 13+
  36 * Bundler (see note below about [developer Ruby setup](#ruby-version-manager-optional))
  37 * JavaScript Runtime
  38
  39 ### Step 1: Install System Dependencies
  40
  41 #### Ubuntu 24.04 LTS
  42
  43 ```bash
  44 sudo apt-get update
  45 sudo apt-get install ruby ruby-dev ruby-bundler \
  46                      libvips-dev libxml2-dev libxslt1-dev nodejs \
  47                      build-essential git-core \
  48                      postgresql postgresql-contrib libpq-dev libsasl2-dev \
  49                      libffi-dev libgd-dev libarchive-dev libyaml-dev libbz2-dev npm
  50 sudo npm install --global yarn
  51 ```
  52
  53 > [!TIP]
  54 > On Ubuntu 24.04, you may need to start PostgreSQL:
  55 >
  56 > ```bash
  57 > sudo systemctl start postgresql.service
  58 > ```
  59
  60 #### Fedora
  61
  62 ```bash
  63 sudo dnf install ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems \
  64                  libxml2-devel nodejs \
  65                  gcc gcc-c++ git \
  66                  postgresql postgresql-server postgresql-contrib libpq-devel \
  67                  perl-podlators libffi-devel gd-devel libarchive-devel \
  68                  libyaml-devel bzip2-devel 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/); OS X 10.7 (Lion) 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/MacOS/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 the latest version of Ruby: `brew install ruby`
 110 * Install other dependencies: `brew install libxml2 gd yarn pngcrush optipng pngquant jhead jpegoptim gifsicle svgo advancecomp vips`
 111 * 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))
 112
 113 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.
 114
 115 ```bash
 116 bundle config build.libxml-ruby --with-xml2-config=/usr/local/opt/libxml2/bin/xml2-config
 117 ```
 118
 119 If you want to run the tests, you need `geckodriver` as well:
 120
 121 ```bash
 122 brew install geckodriver
 123 ```
 124
 125 > [!NOTE]
 126 > 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.
 127
 128 </details>
 129
 130 ### Step 2: Clone the Repository
 131
 132 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:
 133
 134 ```bash
 135 git clone https://github.com/openstreetmap/openstreetmap-website.git
 136 ```
 137
 138 > [!TIP]
 139 > To clone only the most recent version (~23MB), instead use a 'shallow clone':
 140 >
 141 > ```bash
 142 > git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git
 143 > ```
 144 >
 145 > If you want to add in the full history later on, perhaps to run `git blame` or `git log`, run `git fetch --depth=1000000`
 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 just the standard map tiles.
 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 is simpler, and usually faster, you might want more control over the process or the ability to install multiple different versions of software alongside each other. For many developers, [`rbenv`](https://github.com/rbenv/rbenv) is the easiest way to manage multiple different Ruby versions on the same computer - with the added advantage that the installs are all in your home directory, so you don't need administrator permissions.
 261
 262 If you choose to install Ruby and Bundler via `rbenv`, then you do not need to install the system libraries for Ruby:
 263
 264 * For Ubuntu, you do not need to install the following packages: `ruby ruby-dev ruby-bundler`,
 265 * For Fedora, you do not need to install the following packages: `ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems`
 266 * For macOS, you do not need to `brew install ruby`
 267
 268 > [!IMPORTANT]
 269 > On macOS, make sure you've installed a version of Ruby using `rbenv` before running `gem install bundler`!
 270
 271 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:
 272
 273 ```bash
 274 rbenv local $VERSION
 275 ```
 276
 277 Where `$VERSION` is the version you installed. Then install bundler:
 278
 279 ```bash
 280 gem install bundler
 281 ```
 282
 283 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.
 284
 285 ## Production Deployment Notes
 286
 287 > [!WARNING]
 288 > Production deployment requires careful configuration and is significantly different from development setup.
 289
 290 If you want to deploy `openstreetmap-website` for production use, you'll need to make a few changes:
 291
 292 > [!IMPORTANT]
 293 > 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).
 294
 295 * Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.
 296
 297 > [!TIP]
 298 > 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.
 299
 300 * Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production bundle exec i18n export; bundle exec rails assets:precompile`
 301 * Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.