From 65e6b38d4629ba560ea3e74cd05b2372710e90e0 Mon Sep 17 00:00:00 2001 From: Emin Kocan Date: Mon, 16 Jun 2025 16:45:44 +0200 Subject: [PATCH] Restructure INSTALL.md --- INSTALL.md | 214 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 133 insertions(+), 81 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index cb54cb543..1fd5c0d8f 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,35 +1,46 @@ # Installation -These instructions are designed for setting up `openstreetmap-website` for development and testing. -If you want to deploy the software for your own project, then see the notes at the end. +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). -You can install the software directly on your machine, which is the traditional and probably best-supported approach. However, there -are two alternatives which make it easier to get a consistent development environment and may avoid installation difficulties: +## Installation Options -* **Vagrant** This installs the software into a virtual machine. For Vagrant instructions see [VAGRANT.md](VAGRANT.md). -* **Docker** This installs the software using containerization. For Docker instructions see [DOCKER.md](DOCKER.md). +You can setup development enviroment by: -These instructions are based on Ubuntu 24.04 LTS, which is the platform used by the OSMF servers. -The instructions also work, with only minor amendments, for all other current Ubuntu releases, Fedora and MacOSX +### Containerized Installation -We don't recommend attempting to develop or deploy this software on Windows. Some Ruby gems may not be supported. If you need to use Windows the easiest solutions in order are [Docker](DOCKER.md), [Vagrant](VAGRANT.md), and Ubuntu in a virtual machine. +These options provide consistent development environments and may avoid installation difficulties: -## Dependencies +* **🐳 Docker** - Uses containerization. See [DOCKER.md](DOCKER.md) for complete instructions. +* **📦 Vagrant** - Installs in a virtual machine. See [VAGRANT.md](VAGRANT.md) for complete instructions. -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 a large number -of packages required before you can get the various gems installed. +### Manual Installation -## Minimum requirements +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. +--- + +**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. + +> [!WARNING] +> **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). + +## Manual Installation Guide + +### Prerequisites + +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. + +**Minimum requirements:** * Ruby 3.2+ * PostgreSQL 13+ -* Bundler (see note below about [developer Ruby setup](#rbenv)) -* Javascript Runtime +* Bundler (see note below about [developer Ruby setup](#ruby-version-manager-optional)) +* JavaScript Runtime -These can be installed on Ubuntu 24.04 or later with: +### Step 1: Install System Dependencies -``` +#### Ubuntu 24.04 LTS + +```bash sudo apt-get update sudo apt-get install ruby ruby-dev ruby-bundler \ libvips-dev libxml2-dev libxslt1-dev nodejs \ @@ -39,13 +50,16 @@ sudo apt-get install ruby ruby-dev ruby-bundler \ sudo npm install --global yarn ``` -### Alternative platforms +> [!TIP] +> On Ubuntu 24.04, you may need to start PostgreSQL: +> +> ```bash +> sudo systemctl start postgresql.service +> ``` #### Fedora -For Fedora, you can install the minimum requirements with: - -``` +```bash sudo dnf install ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems \ libxml2-devel nodejs \ gcc gcc-c++ git \ @@ -54,177 +68,194 @@ sudo dnf install ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems \ libyaml-devel bzip2-devel nodejs-yarn vips-devel ``` -If you didn't already have PostgreSQL installed then create a PostgreSQL instance and start the server: +On Fedora, if you didn't already have PostgreSQL installed then create a PostgreSQL instance and start the server: -``` +```bash sudo postgresql-setup initdb sudo systemctl start postgresql.service ``` Optionally set PostgreSQL to start on boot: -``` +```bash sudo systemctl enable postgresql.service ``` -#### MacOSX +#### macOS -For MacOSX, you will need XCode installed from the Mac App Store; OS X 10.7 (Lion) or later; and some familiarity with Unix development via the Terminal. +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. -Installing PostgreSQL: +**Installing PostgreSQL:** * Install Postgres.app from https://postgresapp.com/ * Make sure that you've initialized and started Postgresql from the app (there should be a little elephant icon in your systray). * Add PostgreSQL to your path, by editing your profile: -`nano ~/.profile` +```bash +nano ~/.profile +``` and adding: -`export PATH=/Applications/Postgres.app/Contents/MacOS/bin:$PATH` +```bash +export PATH=/Applications/Postgres.app/Contents/MacOS/bin:$PATH +``` After this, you may need to start a new shell window, or source the profile again by running `. ~/.profile`. -Installing other dependencies: +**Installing other dependencies:** * Install Homebrew from https://brew.sh/ * Install the latest version of Ruby: `brew install ruby` * Install other dependencies: `brew install libxml2 gd yarn pngcrush optipng pngquant jhead jpegoptim gifsicle svgo advancecomp vips` -* 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](#rbenv)) +* 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)) -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. +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. -``` +```bash bundle config build.libxml-ruby --with-xml2-config=/usr/local/opt/libxml2/bin/xml2-config ``` If you want to run the tests, you need `geckodriver` as well: -``` +```bash brew install geckodriver ``` -Note that 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. +> [!NOTE] +> 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. + + -## Cloning the repository +### Step 2: Clone the Repository 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: -``` +```bash git clone https://github.com/openstreetmap/openstreetmap-website.git ``` -To clone only the most recent version (~23MB), instead use a 'shallow clone': +> [!TIP] +> To clone only the most recent version (~23MB), instead use a 'shallow clone': +> +> ```bash +> git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git +> ``` +> +> If you want to add in the full history later on, perhaps to run `git blame` or `git log`, run `git fetch --depth=1000000` -``` -git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git -``` - -If you want to add in the full history later on, perhaps to run `git blame` or `git log`, run `git fetch --depth=1000000` +### Step 3: Install Application Dependencies - -## Ruby gems +#### Ruby gems We use [Bundler](https://bundler.io/) to manage the rubygems required for the project. -``` +```bash cd openstreetmap-website bundle install ``` -## Node.js modules +#### Node.js modules We use [Yarn](https://yarnpkg.com/) to manage the Node.js modules required for the project. -``` +```bash bundle exec bin/yarn install ``` -## Prepare local settings file +### Step 4: Prepare Configuration Files -This is a workaround. [See issues/2185 for details](https://github.com/openstreetmap/openstreetmap-website/issues/2185#issuecomment-508676026). +#### Local settings file -``` +> [!NOTE] +> This is a workaround. [See issues/2185 for details](https://github.com/openstreetmap/openstreetmap-website/issues/2185#issuecomment-508676026). + +```bash touch config/settings.local.yml ``` -## Storage setup +#### Storage setup -`openstreetmap-website` needs to be configured with an object storage facility - for -development and testing purposes you can use the example configuration: +`openstreetmap-website` needs to be configured with an object storage facility - for development and testing purposes you can use the example configuration: -``` +```bash cp config/example.storage.yml config/storage.yml ``` -## Database setup +### Step 5: Database Setup -`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. +`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. -``` +```bash cp config/example.database.yml config/database.yml ``` -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. +> [!IMPORTANT] +> 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. -### PostgreSQL account setup +#### PostgreSQL account setup 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. -``` +```bash sudo -u postgres -i createuser -s exit ``` -### Create the databases +#### Create the databases To create the three databases - for development, testing and production - run: -``` +```bash bundle exec rails db:create ``` -### Database structure +#### Database structure To create all the tables, indexes and constraints, run: -``` +```bash bundle exec rails db:migrate ``` -## Running the tests +## Validate Your Installation + +### Running the tests To ensure that everything is set up properly, you should now run: -``` +```bash bundle exec rails test:all ``` This test will take a few minutes, reporting tests run, assertions, and any errors. If you receive no errors, then your installation is successful. -The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored. +> [!NOTE] +> The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored. ### Starting the server Rails comes with a built-in webserver, so that you can test on your own machine without needing a server. Run -``` +```bash bundle exec rails server ``` You can now view the site in your favourite web-browser at [http://localhost:3000/](http://localhost:3000/) -Note that the OSM map tiles you see aren't created from your local database - they are just the standard map tiles. +> [!NOTE] +> The OSM map tiles you see aren't created from your local database - they are just the standard map tiles. -# Configuration +## What's Next? -After installing this software, you may need to carry out some [configuration steps](CONFIGURE.md), depending on your tasks. +🎉 **Congratulations!** You have successfully installed the OpenStreetMap website. -# Ruby development install and versions (optional) +**Next steps:** +* **Configuration:** See [CONFIGURE.md](CONFIGURE.md) for populating the database with data, creating users, setting up OAuth, and other configuration tasks. +* **Contributing:** Check out [CONTRIBUTING.md](CONTRIBUTING.md) for coding style guidelines, testing procedures, and how to submit your contributions. + +## Ruby Version Manager (Optional) 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. @@ -232,18 +263,39 @@ If you choose to install Ruby and Bundler via `rbenv`, then you do not need to i * For Ubuntu, you do not need to install the following packages: `ruby ruby-dev ruby-bundler`, * For Fedora, you do not need to install the following packages: `ruby ruby-devel rubygem-rdoc rubygem-bundler rubygems` -* For MacOSX, you do not need to `brew install ruby` - but make sure you've installed a version of Ruby using `rbenv` before running `gem install bundler`! +* For macOS, you do not need to `brew install ruby` + +> [!IMPORTANT] +> On macOS, make sure you've installed a version of Ruby using `rbenv` before running `gem install bundler`! 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: -``` +```bash rbenv local $VERSION ``` Where `$VERSION` is the version you installed. Then install bundler: -``` +```bash gem install bundler ``` -You should now be able to proceed with the rest of the installation. If you're on MacOSX, make sure you set up the [config override for the libxml2 location](#macosx-bundle-config) _after_ installing bundler. +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. + +## Production Deployment Notes + +> [!WARNING] +> Production deployment requires careful configuration and is significantly different from development setup. + +If you want to deploy `openstreetmap-website` for production use, you'll need to make a few changes: + +> [!IMPORTANT] +> 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). + +* Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts. + +> [!TIP] +> 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. + +* Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production bundle exec i18n export; bundle exec rails assets:precompile` +* Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`. -- 2.39.5