README.md (view raw)
1
2
3[](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
34### Installing
35
36Clone the repo locally:
37
38```shell
39git clone https://git.octree.ch/p/caroster.git
40cd caroster
41```
42
43### Run with Docker
44
45First, edit `docker-compose.yml` to provide your SMTP configuration and optional Mapbox token:
46
47```yaml
48version: "3"
49services:
50 app:
51 ...
52 MAPBOX_TOKEN: pk.mapbox.token
53
54 SMTP_HOST: smtp.myserver.org
55 SMTP_PORT: 587
56 SMTP_USERNAME: user
57 SMTP_PASSWORD: password
58...
59```
60
61Then, create containers with Docker Compose:
62
63```shell
64docker compose up
65```
66
67Wait a few minutes while the application downloads needed packages,
68then go to http://localhost:8080.
69
70You can log on http://localhost:8080/admin with email `admin@example.org`
71and password `caroster`.
72
73## Development
74
75### Frontend
76
77These steps will prepare the frontend to run in development mode.
78
79```shell
80cd frontend
81yarn # or 'npm install'
82yarn dev
83```
84
85The frontend is now accessible on http://localhost:3000
86
87#### Geocoding in development (optional)
88
89Copy your Mapbox token in your .env file under MAPBOX_TOKEN variable and run the app again.
90
91### Backend
92
93These steps will prepare and configure the backend to run in development mode.
94
95> You need a Postgres database running locally. Start one with `docker compose up psql -d`.
96
97```shell
98cd backend
99yarn # or 'npm install'
100cp .env.example .env
101vi .env # Edit with your own configuration
102yarn develop
103```
104
105The Strapi server is now ready and the admin is accessible on http://localhost:1337/admin.
106
107## Running the tests
108
109A few tests are available to check GraphQL endpoints behavior in the `e2e` directory.
110
111First, run Strapi in test mode:
112
113```shell
114cd backend
115cp .env.example .env
116vi .env # Edit with your own configuration
117yarn start-test
118```
119
120Then, run the tests:
121
122```shell
123cd e2e
124yarn
125yarn gql
126yarn test
127```
128
129## Contributing
130
131Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
132
133## Authors
134
135- [Octree](https://github.com/octree-gva) - sustainable startup studio - https://octree.ch
136
137See also the list of [contributors](https://github.com/octree-gva/caroster/graphs/contributors) who participated in this project.
138
139## License
140
141This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details