Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md 2 #183

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 58 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
# OpenStreetMap Calendar

A simple calendar for tracking OpenStreetMap-related activities.
A simple, open calendar for tracking OpenStreetMap-related activities, such as mapping parties, hackathons, conferences, and other community events.

## Key Features

- **Open for Contributions**: Anyone with an OpenStreetMap account can add or manage events.
- **Multilingual Support**: Events and dates can be displayed in different languages based on user preferences.
- **RSS Feeds**: Subscribe to event feeds globally or by specific countries.

## Principles

Expand All @@ -9,50 +15,80 @@ A simple calendar for tracking OpenStreetMap-related activities.

## User Documentation

Please look at [OpenStreetMap Calendar Documentation](https://osmcal.org/documentation/) for information about integration and API.
For information on integration, using the API, or general usage, visit the [OpenStreetMap Calendar Documentation](https://osmcal.org/documentation/).

## Developer Documentation

The repo contains a [dev container](https://containers.dev) configuration, so you can develop without having to install all the dependencies on your machine manually. VS Code and PyCharm/IntelliJ have integrated support and you can even use Github Codespaces.

Alternatively you can install like any other Python/Django project. We're using [poetry](https://python-poetry.org) for managing dependencies. Please look at their documentation for installation instructions.

We support Python ≥ 3.11 and PostgreSQL ≥ 15. (Older versions might work, but no guarantees).
### Requirements

- Python ≥ 3.11
- PostgreSQL ≥ 15 with PostGIS

### Setup Instructions

1. **Clone the Repository**:
```
git clone https://github.com/<your-repo>/osmcal.git
cd osmcal
```

### Database
2. **Install Dependencies**:
Use Poetry to install all necessary dependencies:
```
poetry install
```

You need a running PostgreSQL database with PostGIS installed. If you're using the dev container, the DB is automatically started and set up.
3. **Configure the Database**:
Ensure a PostgreSQL database with PostGIS is available. If using the dev container, the database is automatically started. For manual setup, create an empty database named `osmcal`.

If you set this up manually, make sure you have an empty DB before starting. By default we're using the `osmcal` for user and DB with no password set. For more details, check `osmcal/settings.py`.
Update the database settings in `osmcal/settings.py` if needed.

4. **Run Database Migrations**:
```
make migrate
```

5. **Start the Development Server**:
```
make devserver
```

6. **Load Test Data (Optional)**:
If needed, load sample data:
```
make fixtures
```

### Running Tests

To ensure everything is working correctly, run the tests:
```
make test
```

### Developer Server
### Mock Login for Development

In order to facilitate testing, you can use a fake login locally without having to setup OAuth first. To do this, scroll down to the footer. In debug mode, there is a link called "Mock login" which will instantly log you in as a normal user.
During development, you can use a fake login without setting up OAuth. Scroll to the footer in debug mode and click "Mock login" to instantly log in as a normal user.

To prepare for application launch run the database migrations:
## API Documentation

```
make migrate
```
The API is described using OpenAPI 3, and the schema is located in `/api/schema/`. The live version is available [here](https://osmcal.org/static/api.html).

and then the local server:
## Support and Contact

```
make devserver
```
For questions, feedback, or support, feel free to reach out via the following channels:

If you need test data, you can load some using:
- **Matrix Channel**: Join the discussion at [#osmcal:openstreetmap.org](https://matrix.to/#/#osmcal:mustelo.de).
- **GitHub Issues**: Report bugs or request features on the [issue tracker](https://github.com/thomersch/openstreetmap-calendar/issues).

```
make fixtures
```
## Contributing

## API Documentation
We welcome contributions! Check out the developer documentation above for setup instructions, and feel free to submit pull requests or open issues. Translations can be found in the folder https://github.com/thomersch/openstreetmap-calendar/blob/master/osmcal/locale

## License

The API is described using OpenAPI 3, the schema is located in `/api/schema/`. The currently live version is [visible here](https://osmcal.org/static/api.html).
This project is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/thomersch/openstreetmap-calendar/blob/master/LICENSE) file for details.