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)
Copy file name to clipboardExpand all lines: doc/DEVCONTAINER.md
+17-8Lines changed: 17 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -84,39 +84,48 @@ If you want to add in the full history later on, perhaps to run `git blame` or `
84
84
85
85
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.
86
86
87
-
87
+
88
88
89
89
## Open the project in a container
90
90
91
91
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".
92
92
93
-
93
+
94
94
95
95
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.
96
96
97
-
97
+
98
98
99
99
Eventually this will present you with a development environment ready to go. In subsequent occasions this should be much faster.
100
100
101
101
## Done!
102
102
103
103
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)":
104
104
105
-
105
+
106
106
107
107
From this terminal, you can run the test suite with `bundle exec rails test:all`:
108
108
109
-
109
+
110
110
111
111
Hopefully it should be all green? 🤞 You can also start a development server with `bundle exec rails s`:
112
112
113
-
113
+
114
114
115
115
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.
116
116
117
-
## Other useful configuration
117
+
> [!NOTE]
118
+
> 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.
118
119
119
-
See [`CONFIGURE.md`](CONFIGURE.md) for information on how to manage users and enable OAuth for iD, JOSM etc.
120
+
## What's next?
121
+
122
+
🎉 **Congratulations!** You have successfully installed the OpenStreetMap website.
123
+
124
+
**Next steps:**
125
+
***Configuration:** See [CONFIGURE.md](CONFIGURE.md) for populating the database with data, creating users, setting up OAuth, and other configuration tasks.
126
+
***Contributing:** Check out [CONTRIBUTING.md](CONTRIBUTING.md) for coding style guidelines, testing procedures, and how to submit your contributions.
127
+
128
+
Any terminal commands must be run like above, in the terminal provided by VS Code to run within the devcontainer.
Copy file name to clipboardExpand all lines: doc/DOCKER.md
+34-74Lines changed: 34 additions & 74 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -79,105 +79,65 @@ 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
83
84
-
Run the Rails database migrations:
84
+
At this point, the Docker container can be used although there are a couple of steps missing to complete the install.
85
+
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
+
> [!IMPORTANT]
95
+
> Unless otherwise stated, make sure that you are in this shell when following any other instructions.
93
96
94
-
```bash
95
-
docker compose run --rm web bundle exec rails db:test:prepare
96
-
```
97
+
### Create the databases
97
98
98
-
Run the test suite:
99
+
To create all databases and set up all databases, run:
99
100
100
101
```bash
101
-
docker compose run --rm web bundle exec rails test:all
102
+
bundle exec rails db:create
102
103
```
103
104
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
122
-
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.
124
-
125
-
For example, let's download the District of Columbia from Geofabrik or [any other region](https://download.geofabrik.de):
Hopefully that's it? Let's check that things are working properly.
130
108
131
-
You can now use Docker to load this extract into your local Docker-based OSM instance:
109
+
### Run the tests
132
110
133
-
```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"
143
-
```
111
+
Run the test suite:
144
112
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"
113
+
```bash
114
+
bundle exec rails test:all
157
115
```
158
116
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.
160
-
161
-
### Additional Configuration
117
+
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.
162
118
163
-
See [`CONFIGURE.md`](CONFIGURE.md) for information on how to manage users and enable OAuth for iD, JOSM etc.
119
+
> [!NOTE]
120
+
> The unit tests may output parser errors related to "Attribute lat redefined." These can be ignored.
164
121
165
-
### Bash
122
+
### Start the development server
166
123
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:
124
+
Rails comes with a built-in webserver, so that you can test on your own machine without needing a server. Run:
168
125
169
126
```bash
170
-
docker compose run --rm web bash
127
+
bundle exec rails server
171
128
```
172
129
173
-
Alternatively, if you want to use the already-running `web` container then you can `exec` into it via:
130
+
You can now view the site in your favourite web browser at [http://localhost:3000/](http://localhost:3000/)
174
131
175
-
```bash
176
-
docker compose exec web bash
177
-
```
132
+
> [!NOTE]
133
+
> 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
134
179
-
Similarly, if you want to `exec` in the db container use:
135
+
## What's next?
180
136
181
-
```bash
182
-
docker compose exec db bash
183
-
```
137
+
🎉 **Congratulations!** You have successfully installed the OpenStreetMap website.
138
+
139
+
**Next steps:**
140
+
***Configuration:** See [CONFIGURE.md](CONFIGURE.md) for populating the database with data, creating users, setting up OAuth, and other configuration tasks.
141
+
***Contributing:** Check out [CONTRIBUTING.md](CONTRIBUTING.md) for coding style guidelines, testing procedures, and how to submit your contributions.
142
+
143
+
Don't forget 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.md](DOCKER.md).
14
+
- To use Docker via [Development Containers](https://containers.dev) (devcontainers), see [DEVCONTAINER.md](DEVCONTAINER.md).
15
+
16
+
### Manual Installation
17
+
18
+
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.
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
+
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