1![Caroster](./banner.jpg)
  2
  3[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
  4
  5# About Caroster
  6
  7Caroster is a simple, free and open-source carpooling app designed to makes it easy to organize shared trips for an event, a party, a seminar, a sport game, a camp or any other trip. 
  8
  9Our vision is to make Caroster a true digital common, a project collectively governed by its community, beyond any individual or organization. Our ambition is for Caroster to survive its creators, growing through shared governance and open collaboration.
 10
 11Caroster is developed and provided by [Octree](https://octree.ch/), a sustainable startup studio based in Geneva. Octree is made up of a committed team that aims to provide tools that respect human and ecological values.
 12
 13We believe that all creations should be free of rights, freely modifiable or duplicable, to serve as many people as possible. We prefer cooperation to competition, so Caroster is an open source project under the GNU - AGPL 3.0 license.
 14
 15We welcome contributions from anyone who shares our vision of a more sustainable and cooperative world :)
 16
 17> Are you on GitHub ? Please use the [reference repository on GitLab](https://git.octree.ch/p/caroster) for issues and pull requests.
 18
 19## Features
 20
 21This project makes it easy to:
 22
 23- 📅 Create a dedicated carpool page for each event
 24- ⚙️ Customize event settings (description, location, date)
 25- 🗺️ See trips proposed on a map
 26- 🚗 Propose a trip as driver in just a few clicks
 27- 👤 Add to a trip as passenger in just a few clicks
 28- ⏳ Request a trip in the waiting list menu for passengers
 29- 🔄 Manage round trips for the event
 30- 🔍 Search for a trip by departure location with a search bar
 31- 🔔 Get email notifications when a new trip is available
 32- 📬 Receive weekly summary emails for organizers
 33- 🛠️ Manage event with administrator roles (_Caroster paid only_)
 34
 35## Getting Started
 36
 37These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
 38
 39Caroster is composed of two parts:
 40
 41- A frontend app based on [NextJS](https://nextjs.org/)
 42- A backend server using [Strapi](https://strapi.io/)
 43
 44> Caroster is currently in Beta. Big changes can happen, especially in terms of data architecture.
 45
 46### Prerequisites
 47
 48To fully utilize your instance of Caroster, you will need an SMTP configuration to send emails.
 49
 50#### (Optional) Mapbox token 
 51
 52In order to activate geocoding and map features, you will need a Mapbox token.
 53
 54[Create a mapbox account](https://account.mapbox.com/auth/signup/) if you don't have any and [generate your token for free](https://docs.mapbox.com/help/getting-started/access-tokens/#:~:text=You%20can%20find%20your%20access,using%20the%20Mapbox%20Tokens%20API.). 
 55
 56There is no need to setup a payment method as long as you don't exceed [the temporary geocoding api free rate ](https://www.mapbox.com/pricing#temporary-geocoding-api), but if you do so, the app will still work and geocoding will simply disable till the end of the ongoing month.
 57
 58Copy the mapbox token in the .env file as a value for "MAPBOX_TOKEN" variable to start using geocoding and map features;
 59
 60#### Tiles server
 61
 62You can use the TOKEN_FREE_TILES variables in the .env file to setup a tiles server used by the map features. By default, we use the [© OpenStreetMap ](https://www.openstreetmap.org/copyright/en) test server. 
 63
 64Make sure to respect the copyrights of the tiles server you setup, or those from [© OpenStreetMap ](https://www.openstreetmap.org/copyright/en) if you keep the default settings.
 65
 66> :warning: Be aware that some services might require a token to use their tiles server.
 67>
 68> We don't have yet developed a way to obfuscate this token from the users.
 69
 70> :warning: This means anyone accessing the application will be able to use this token on your behalf, which exposes you to substantial risks (financial, legal, reputational, operational) that may affect you and the disponibility of the service.
 71
 72### Installing
 73
 74Clone the repo locally:
 75
 76```shell
 77git clone https://git.octree.ch/p/caroster.git
 78cd caroster
 79```
 80
 81### Run with Docker
 82
 83First, edit `docker-compose.yml` to provide your SMTP configuration and optional Mapbox token:
 84
 85```yaml
 86version: "3"
 87services:
 88  app:
 89    ...
 90    MAPBOX_TOKEN: pk.mapbox.token
 91
 92    SMTP_HOST: smtp.myserver.org
 93    SMTP_PORT: 587
 94    SMTP_USERNAME: user
 95    SMTP_PASSWORD: password
 96...
 97```
 98
 99Then, create containers with Docker Compose:
100
101```shell
102docker compose up
103```
104
105Wait a few minutes while the application downloads needed packages,
106then go to http://localhost:8080.
107
108You can log on http://localhost:8080/admin with email `admin@example.org`
109and password `caroster`.
110
111## Development
112
113### Frontend
114
115These steps will prepare the frontend to run in development mode.
116
117```shell
118cd frontend
119yarn # or 'npm install'
120yarn dev
121```
122
123The frontend is now accessible on http://localhost:3000
124
125### Backend
126
127These steps will prepare and configure the backend to run in development mode.
128
129> You need a Postgres database running locally. Start one with `docker compose up psql -d`.
130
131```shell
132cd backend
133yarn # or 'npm install'
134cp .env.example .env
135vi .env # Edit with your own configuration
136yarn develop
137```
138
139The Strapi server is now ready and the admin is accessible on http://localhost:1337/admin.
140
141## Running the tests
142
143A few tests are available to check GraphQL endpoints behavior in the `e2e` directory.
144
145First, run Strapi in test mode:
146
147```shell
148cd backend
149cp .env.example .env
150vi .env # Edit with your own configuration
151yarn start-test
152```
153
154Then, run the tests:
155
156```shell
157cd e2e
158yarn
159yarn gql
160yarn test
161```
162
163## Contributing
164
165Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for submitting pull requests to us.
166All contributors and persons involved in the project follow our [code of conduct](CODE_OF_CONDUCT.md).
167
168*N.B.* Use [our Gitlab](https://git.octree.ch/p/caroster) to submit any PR or issues
169
170## Authors
171
172- [Octree](https://github.com/octree-gva) - sustainable startup studio - https://octree.ch
173
174See also the list of [contributors](https://github.com/octree-gva/caroster/graphs/contributors) who participated in this project.
175
176## License
177
178This project is licensed under the GNU Affero General Public License v3 - see the [LICENSE.md](LICENSE.md) file for details