DRY docs

.gitignore

@@ -13,7 +13,6 @@ config/environments/*.local.yml
 config/settings.local.yml
 config/settings/*.local.yml
 coverage
-doc
 log
 node_modules
 public/assets

CONTRIBUTING.md

@@ -22,7 +22,7 @@ This guide covers our development workflow, coding standards, and how to get you
 
 > [!NOTE]
 > We don't assign issues to individual contributors. You are welcome to work on any issue, and there's no need to ask first.
-> For more details see [our FAQ](FAQ.md)
+> For more details see [our FAQ](doc/FAQ.md)
 
 We welcome the community to contribute to this repository in any form:
 
@@ -81,7 +81,7 @@ Here's the typical contribution workflow:
 
 1. **Find an Issue**: Browse our [issues](https://github.com/openstreetmap/openstreetmap-website/issues) or identify a bug/feature you'd like to work on
 2. **Fork, Clone & Branch**: Fork the repository, clone it to your local machine, and create a new branch for your work. Avoid working directly on the `master` branch.
-3. **Set Up**: Follow the [installation guide](INSTALL.md) to set up your development environment
+3. **Set Up**: Follow the [installation guide](doc/INSTALL.md) to set up your development environment
 4. **Develop**: Make your changes following our [code quality guidelines](#code-quality-guidelines)
 5. **Test**: Write tests for your changes and ensure all existing tests pass
 6. **Commit**: Write clear commit messages following our [guidelines](#committing)

README.md

@@ -26,7 +26,7 @@ a copy of which can be found in the [LICENSE](LICENSE) file.
 # Installation
 
 `openstreetmap-website` is a Ruby on Rails application that uses PostgreSQL as its database, and has a large
-number of dependencies for installation. For full details please see [INSTALL.md](INSTALL.md).
+number of dependencies for installation. For full details please see [INSTALL.md](doc/INSTALL.md).
 
 # Development
 

config/devcontainer.database.yml

@@ -1,4 +1,4 @@
-# This configuration is tailored for use with devcontainers. See DEVCONTAINER.md for more information.
+# This configuration is tailored for use with devcontainers. See doc/DEVCONTAINER.md for more information.
 
 development:
   adapter: postgresql

config/docker.database.yml

@@ -1,4 +1,4 @@
-# This configuration is tailored for use with docker compose. See DOCKER.md for more information.
+# This configuration is tailored for use with docker compose. See doc/DOCKER.md for more information.
 
 development:
   adapter: postgresql

CONFIGURE.md → doc/CONFIGURE.md

@@ -264,4 +264,4 @@ If you need additional assistance:
 
 ## Contributing
 
-For information on contributing changes to the code, see [CONTRIBUTING.md](CONTRIBUTING.md)
+For information on contributing changes to the code, see [CONTRIBUTING.md](../CONTRIBUTING.md)

DEVCONTAINER.md → doc/DEVCONTAINER.md

@@ -84,39 +84,48 @@ If you want to add in the full history later on, perhaps to run `git blame` or `
 
 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.
 
-![VS Code: panel to install extensions](./docs/assets/vscode-devcontainers-extension.png)
+![VS Code: panel to install extensions](./assets/vscode-devcontainers-extension.png)
 
 ## Open the project in a container
 
 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".
 
-![VS Code: command to open in a devcontainer](./docs/assets/vscode-dev-reopen.png)
+![VS Code: command to open in a devcontainer](./assets/vscode-dev-reopen.png)
 
 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.
 
-![VS Code: notification that VS Code is connecting to the Dev Container](./docs/assets/vscode-connecting-to-devcontainer.png)
+![VS Code: notification that VS Code is connecting to the Dev Container](./assets/vscode-connecting-to-devcontainer.png)
 
 Eventually this will present you with a development environment ready to go. In subsequent occasions this should be much faster.
 
 ## Done!
 
 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)":
 
-![VS Code: command to open a terminal](./docs/assets/vscode-create-terminal.png)
+![VS Code: command to open a terminal](./assets/vscode-create-terminal.png)
 
 From this terminal, you can run the test suite with `bundle exec rails test:all`:
 
-![Running the test suite in the terminal](./docs/assets/vscode-rails-test-all.png)
+![Running the test suite in the terminal](./assets/vscode-rails-test-all.png)
 
 Hopefully it should be all green? 🤞 You can also start a development server with `bundle exec rails s`:
 
-![Running the dev server in the terminal](./docs/assets/vscode-rails-server.png)
+![Running the dev server in the terminal](./assets/vscode-rails-server.png)
 
 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.
 
-## Other useful configuration
+> [!NOTE]
+> 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.
 
-See [`CONFIGURE.md`](CONFIGURE.md) for information on how to manage users and enable OAuth for iD, JOSM etc.
+## What's next?
+
+🎉 **Congratulations!** You have successfully installed the OpenStreetMap website.
+
+**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.
+
+Any terminal commands must be run like above, in the terminal provided by VS Code to run within the devcontainer.
 
 ## Other tools
 

DOCKER.md → doc/DOCKER.md

@@ -79,105 +79,65 @@ This will launch one Docker container for each 'service' specified in `docker-co
 - You can tail logs of a running container with a command like this: `docker compose logs -f web` or `docker compose logs -f db`.
 - Instead of running the containers in the background with the `-d` flag, you can launch the containers in the foreground with `docker compose up`. The downside of this is that the logs of all the 'services' defined in `docker-compose.yml` will be intermingled. If you don't want this you can mix and match - for example, you can run the database in background with `docker compose up -d db` and then run the Rails app in the foreground via `docker compose up web`.
 
-### Migrations
+## Running commands
 
-Run the Rails database migrations:
+At this point, the Docker container can be used although there are a couple of steps missing to complete the install.
+
+From now on, any commands should be run within the container. To do this, first you need to open a shell within it:
 
 ```bash
-docker compose run --rm web bundle exec rails db:migrate
+docker compose run --rm web bash
 ```
 
-### Tests
+This will open a shell where you can enter commands. These commands will run within the context of the container, without affecting your own machine outside your working directory.
 
-Prepare the test database:
+> [!IMPORTANT]
+> Unless otherwise stated, make sure that you are in this shell when following any other instructions.
 
-```bash
-docker compose run --rm web bundle exec rails db:test:prepare
-```
+### Create the databases
 
-Run the test suite:
+To create all databases and set up all databases, run:
 
 ```bash
-docker compose run --rm web bundle exec rails test:all
+bundle exec rails db:create
 ```
 
-> [!TIP]
-> If you encounter errors about missing assets, ensure your asset pipeline is correctly configured for your environment.
->
-> In production, assets must be precompiled for better performance:
->
-> ```bash
-> docker compose run --rm web bundle exec rake assets:precompile
-> ```
->
->In development, missing assets usually indicate a configuration or dependency issue.
-> Precompiling assets in *development* will disable dynamic compilation and make debugging harder due to fingerprinted assets.
-> To clean the assets you can run:
->
-> ```bash
-> docker compose run --rm web bundle exec rake assets:clobber
-> ```
-
-### Loading an OSM extract
-
-This installation comes with no geographic data loaded. You can either create new data using one of the editors (Potlatch 2, iD, JOSM etc) or by loading an OSM extract. Here an example for loading an OSM extract into your Docker-based OSM instance.
-
-For example, let's download the District of Columbia from Geofabrik or [any other region](https://download.geofabrik.de):
+## Validate Your Installation
 
-```bash
-wget https://download.geofabrik.de/north-america/us/district-of-columbia-latest.osm.pbf
-```
+Hopefully that's it? Let's check that things are working properly.
 
-You can now use Docker to load this extract into your local Docker-based OSM instance:
+### Run the tests
 
-```bash
-docker compose run --rm web osmosis \
-    -verbose    \
-    --read-pbf district-of-columbia-latest.osm.pbf \
-    --log-progress \
-    --write-apidb \
-        host="db" \
-        database="openstreetmap" \
-        user="openstreetmap" \
-        validateSchemaVersion="no"
-```
+Run the test suite:
 
-**Windows users:** Powershell uses `` ` `` and CMD uses `^` at the end of each line, e.g.:
-
-```powershell
-docker compose run --rm web osmosis `
-    -verbose    `
-    --read-pbf district-of-columbia-latest.osm.pbf `
-    --log-progress `
-    --write-apidb `
-        host="db" `
-        database="openstreetmap" `
-        user="openstreetmap" `
-        validateSchemaVersion="no"
+```bash
+bundle exec rails test:all
 ```
 
-Once you have data loaded for Washington, DC you should be able to navigate to [`http://localhost:3000/#map=12/38.8938/-77.0146`](http://localhost:3000/#map=12/38.8938/-77.0146) to begin working with your local instance.
-
-### Additional Configuration
+This test will take a few minutes, reporting tests run, assertions, and any errors. If you receive no errors, then your installation was successful. On occasion some tests may fail randomly and will pass if run again. We are working towards avoiding this, but it can still happen.
 
-See [`CONFIGURE.md`](CONFIGURE.md) for information on how to manage users and enable OAuth for iD, JOSM etc.
+> [!NOTE]
+> The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored.
 
-### Bash
+### Start the development server
 
-If you want to get into a web container and run specific commands you can fire up a throwaway container to run bash in via:
+Rails comes with a built-in webserver, so that you can test on your own machine without needing a server. Run:
 
 ```bash
-docker compose run --rm web bash
+bundle exec rails server
 ```
 
-Alternatively, if you want to use the already-running `web` container then you can `exec` into it via:
+You can now view the site in your favourite web browser at [http://localhost:3000/](http://localhost:3000/)
 
-```bash
-docker compose exec web bash
-```
+> [!NOTE]
+> 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.
 
-Similarly, if you want to `exec` in the db container use:
+## What's next?
 
-```bash
-docker compose exec db bash
-```
+🎉 **Congratulations!** You have successfully installed the OpenStreetMap website.
+
+**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.
+
+Don't forget to **run any commands in a shell within the container**, as instructed above under "Running commands".

doc/INSTALL.md

@@ -0,0 +1,41 @@
+# Installation
+
+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).
+
+## Installation Options
+
+There is more than one way to set up a development environment.
+
+### Containerized Installation
+
+We offer containerized environments with Docker which may avoid installation difficulties:
+
+- To use Docker manually, see [DOCKER.md](DOCKER.md).
+- To use Docker via [Development Containers](https://containers.dev) (devcontainers), see [DEVCONTAINER.md](DEVCONTAINER.md).
+
+### Manual Installation
+
+This option involves manually installing dependencies directly on your machine. This gives you the most control and is often preferred by experienced developers on Linux systems.
+
+> [!WARNING]
+> **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.
+
+To install manually, see [MANUAL_INSTALL.md](MANUAL_INSTALL.md).
+
+## 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/`.