README.md (view raw)
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# Caroster - Group carpool to your event
6
7Caroster is an easy and free app to organize group carpooling for an event, a party, a seminar, a sports event, a camp, a ski trip…
8
9> Are you on GitHub ? Please use the [reference repository on GitLab](https://git.octree.ch/p/caroster) for issues and pull requests.
10
11## Getting Started
12
13These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
14
15Caroster is composed of two parts:
16
17- A frontend app based on [NextJS](https://nextjs.org/)
18- A backend server using [Strapi](https://strapi.io/)
19
20> Caroster is currently in Beta. Big changes can happen, especially in terms of data architecture.
21
22### Prerequisites
23
24To fully utilize your instance of Caroster, you will need an SMTP configuration to send emails.
25
26#### (Optional) Mapbox token
27
28In order to activate geocoding and map features, you will need a Mapbox token.
29
30[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.).
31
32There 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.
33
34Copy the mapbox token in the .env file as a value for "MAPBOX_TOKEN" variable to start using geocoding and map features;
35
36#### Tiles server
37
38You 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.
39
40Make 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.
41
42> :warning: Be aware that some services might require a token to use their tiles server.
43>
44> We don't have yet developed a way to obfuscate this token from the users.
45
46> :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.
47
48### Installing
49
50Clone the repo locally:
51
52```shell
53git clone https://git.octree.ch/p/caroster.git
54cd caroster
55```
56
57### Run with Docker
58
59First, edit `docker-compose.yml` to provide your SMTP configuration and optional Mapbox token:
60
61```yaml
62version: "3"
63services:
64 app:
65 ...
66 MAPBOX_TOKEN: pk.mapbox.token
67
68 SMTP_HOST: smtp.myserver.org
69 SMTP_PORT: 587
70 SMTP_USERNAME: user
71 SMTP_PASSWORD: password
72...
73```
74
75Then, create containers with Docker Compose:
76
77```shell
78docker compose up
79```
80
81Wait a few minutes while the application downloads needed packages,
82then go to http://localhost:8080.
83
84You can log on http://localhost:8080/admin with email `admin@example.org`
85and password `caroster`.
86
87## Development
88
89### Frontend
90
91These steps will prepare the frontend to run in development mode.
92
93```shell
94cd frontend
95yarn # or 'npm install'
96yarn dev
97```
98
99The frontend is now accessible on http://localhost:3000
100
101### Backend
102
103These steps will prepare and configure the backend to run in development mode.
104
105> You need a Postgres database running locally. Start one with `docker compose up psql -d`.
106
107```shell
108cd backend
109yarn # or 'npm install'
110cp .env.example .env
111vi .env # Edit with your own configuration
112yarn develop
113```
114
115The Strapi server is now ready and the admin is accessible on http://localhost:1337/admin.
116
117## Running the tests
118
119A few tests are available to check GraphQL endpoints behavior in the `e2e` directory.
120
121First, run Strapi in test mode:
122
123```shell
124cd backend
125cp .env.example .env
126vi .env # Edit with your own configuration
127yarn start-test
128```
129
130Then, run the tests:
131
132```shell
133cd e2e
134yarn
135yarn gql
136yarn test
137```
138
139## Contributing
140
141Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
142
143## Authors
144
145- [Octree](https://github.com/octree-gva) - sustainable startup studio - https://octree.ch
146
147See also the list of [contributors](https://github.com/octree-gva/caroster/graphs/contributors) who participated in this project.
148
149## License
150
151This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details