You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ This guide covers our development workflow, coding standards, and how to get you
22
22
23
23
> [!NOTE]
24
24
> We don't assign issues to individual contributors. You are welcome to work on any issue, and there's no need to ask first.
25
-
> For more details see [our FAQ](FAQ.md)
25
+
> For more details see [our FAQ](doc/FAQ.md).
26
26
27
27
We welcome the community to contribute to this repository in any form:
28
28
@@ -81,7 +81,7 @@ Here's the typical contribution workflow:
81
81
82
82
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
83
83
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.
84
-
3.**Set Up**: Follow the [installation guide](INSTALL.md) to set up your development environment
84
+
3.**Set Up**: Follow the [installation guide](doc/INSTALL.md) to set up your development environment
85
85
4.**Develop**: Make your changes following our [code quality guidelines](#code-quality-guidelines)
86
86
5.**Test**: Write tests for your changes and ensure all existing tests pass
87
87
6.**Commit**: Write clear commit messages following our [guidelines](#committing)
To build local Docker images run from the root directory of the repository:
64
64
65
-
```bash
65
+
```
66
66
docker compose build
67
67
```
68
68
69
69
If this is your first time running or you have removed cache this will take some time to complete. Once the Docker images have finished building you can launch the images as containers.
70
70
71
71
To launch the app run:
72
72
73
-
```bash
73
+
```
74
74
docker compose up -d
75
75
```
76
76
@@ -79,105 +79,60 @@ This will launch one Docker container for each 'service' specified in `docker-co
79
79
- You can tail logs of a running container with a command like this: `docker compose logs -f web` or `docker compose logs -f db`.
80
80
- 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`.
81
81
82
-
### Migrations
82
+
### Running commands
83
+
84
+
At this point, the Docker container can be used although there are a couple of steps missing to complete the install.
83
85
84
-
Run the Rails database migrations:
86
+
From now on, any commands should be run within the container. To do this, first you need to open a shell within it:
85
87
86
88
```bash
87
-
docker compose run --rm web bundle exec rails db:migrate
89
+
docker compose run --rm web bash
88
90
```
89
91
90
-
### Tests
92
+
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.
91
93
92
-
Prepare the test database:
94
+
Unless otherwise stated, make sure that you are in this shell when following any other instructions.
93
95
94
-
```bash
95
-
docker compose run --rm web bundle exec rails db:test:prepare
96
-
```
96
+
### Create the databases
97
97
98
-
Run the test suite:
98
+
To create all databases and set up all databases, run:
99
99
100
100
```bash
101
-
docker compose run --rm web bundle exec rails test:all
101
+
bundle exec rails db:create
102
102
```
103
103
104
-
> [!TIP]
105
-
> If you encounter errors about missing assets, ensure your asset pipeline is correctly configured for your environment.
106
-
>
107
-
> In production, assets must be precompiled for better performance:
108
-
>
109
-
> ```bash
110
-
> docker compose run --rm web bundle exec rake assets:precompile
111
-
>```
112
-
>
113
-
>In development, missing assets usually indicate a configuration or dependency issue.
114
-
> Precompiling assets in*development* will disable dynamic compilation and make debugging harder due to fingerprinted assets.
115
-
> To clean the assets you can run:
116
-
>
117
-
>```bash
118
-
> docker compose run --rm web bundle exec rake assets:clobber
119
-
>```
120
-
121
-
### Loading an OSM extract
104
+
## Validate Your Installation
122
105
123
-
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.
106
+
Hopefully that's it? Let's check that things are working properly.
124
107
125
-
For example, let's download the District of Columbia from Geofabrik or [any other region](https://download.geofabrik.de):
You can now use Docker to load this extract into your local Docker-based OSM instance:
110
+
Run the test suite:
132
111
133
112
```bash
134
-
docker compose run --rm web osmosis \
135
-
-verbose \
136
-
--read-pbf district-of-columbia-latest.osm.pbf \
137
-
--log-progress \
138
-
--write-apidb \
139
-
host="db" \
140
-
database="openstreetmap" \
141
-
user="openstreetmap" \
142
-
validateSchemaVersion="no"
113
+
bundle exec rails test:all
143
114
```
144
115
145
-
**Windows users:** Powershell uses `` ` `` and CMD uses `^` at the end of each line, e.g.:
146
-
147
-
```powershell
148
-
docker compose run --rm web osmosis `
149
-
-verbose `
150
-
--read-pbf district-of-columbia-latest.osm.pbf `
151
-
--log-progress `
152
-
--write-apidb `
153
-
host="db" `
154
-
database="openstreetmap" `
155
-
user="openstreetmap" `
156
-
validateSchemaVersion="no"
157
-
```
116
+
This test will take a few minutes, reporting tests run, assertions, and any errors. If you receive no errors, then your installation is successful.
158
117
159
-
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.
118
+
> [!NOTE]
119
+
> The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored.
160
120
161
-
### Additional Configuration
121
+
### Start the development server
162
122
163
-
See [`CONFIGURE.md`](CONFIGURE.md) for information on how to manage users and enable OAuth for iD, JOSM etc.
164
-
165
-
### Bash
166
-
167
-
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:
123
+
Rails comes with a built-in webserver, so that you can test on your own machine without needing a server. Run:
168
124
169
125
```bash
170
-
docker compose run --rm web bash
126
+
bundle exec rails server
171
127
```
172
128
173
-
Alternatively, if you want to use the already-running `web` container then you can `exec` into it via:
129
+
You can now view the site in your favourite web-browser at [http://localhost:3000/](http://localhost:3000/)
174
130
175
-
```bash
176
-
docker compose exec web bash
177
-
```
131
+
> [!NOTE]
132
+
> 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.
178
133
179
-
Similarly, if you want to `exec` in the db container use:
134
+
## You are done!
180
135
181
-
```bash
182
-
docker compose exec db bash
183
-
```
136
+
If all the above worked, congratulations! You can now start working on this codebase.
137
+
138
+
Note that there are additional configuration steps that may make your life easier. We recommend that you read [CONFIGURE.md](CONFIGURE.md) next. Remember to run any commands in a shell within the container, as instructed above under "Running commands".
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. 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 containerized setup using [Docker](DOCKER.md).
22
+
23
+
To install manually, see [MANUAL_INSTALL.md](MANUAL_INSTALL.md).
24
+
25
+
## Production Deployment Notes
26
+
27
+
> [!WARNING]
28
+
> Production deployment requires careful configuration and is significantly different from development setup.
29
+
30
+
If you want to deploy `openstreetmap-website` for production use, you'll need to make a few changes:
31
+
32
+
> [!IMPORTANT]
33
+
> 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).
34
+
35
+
* Passenger will, by design, use the Production environment and therefore the production database - make sure it contains the appropriate data and user accounts.
36
+
37
+
> [!TIP]
38
+
> 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.
39
+
40
+
* Make sure you generate the i18n files and precompile the production assets: `RAILS_ENV=production bundle exec i18n export; bundle exec rails assets:precompile`
41
+
* Make sure the web server user as well as the rails user can read, write and create directories in `tmp/`.
0 commit comments