mirror of
https://github.com/plausible/analytics.git
synced 2024-12-26 02:55:02 +03:00
7505584cf8
* chore(docker): improve repeat contributions workflow * This change adds two new commands to gracefully stop and remove the Postgres and Clickhouse docker containers. To do so, it also gives them a recognizable name. * Additionally, the Postgres container is updated to use a named volume for its data. This lower friction for repeat contributions where one would otherwise sign up and activate their accounts again and again each time. * Apple M1 compatibility for local development * Patch upgrade for Python to a version that is built without errors * Use a new community image for clickhouse that's ARM64 compatible * Update contribution docs
41 lines
2.2 KiB
Markdown
41 lines
2.2 KiB
Markdown
# Contributing
|
|
|
|
## Development setup
|
|
|
|
The easiest way to get up and running is to [install](https://docs.docker.com/get-docker/) and use Docker for running both Postgres and Clickhouse.
|
|
|
|
Make sure Docker, Elixir, Erlang and Node.js are all installed on your development machine.
|
|
|
|
### Start the environment:
|
|
|
|
1. Run both `make postgres` and `make clickhouse`.
|
|
1. If you are using Apple Silicon (any of the M1 or similar SoC variants), `make clickhouse-arm` offers a development-only substitute that will work on your local machine. Not intended for production.
|
|
2. You can set up everything with `make install`, alternatively run each command separately:
|
|
1. Run `mix deps.get`. This will download the required Elixir dependencies.
|
|
2. Run `mix ecto.create`. This will create the required databases in both Postgres and Clickhouse.
|
|
3. Run `mix ecto.migrate` to build the database schema.
|
|
4. Run `npm ci --prefix assets` to install the required node dependencies.
|
|
3. Run `make server` or `mix phx.server` to start the Phoenix server.
|
|
4. The system is now available on `localhost:8000`.
|
|
|
|
### Creating an account
|
|
|
|
1. Navigate to `http://localhost:8000/register` and fill in the form.
|
|
2. Fill in the rest of the forms and for the domain use `dummy.site`
|
|
3. Skip the JS snippet and click start collecting data.
|
|
4. Run `make dummy_event` from the terminal to generate a fake pageview event for the dummy site.
|
|
5. You should now be all set!
|
|
|
|
### Stopping Docker containers
|
|
|
|
1. Stop and remove the Postgres container with `make postgres-stop`.
|
|
2. Stop and remove the Clickhouse container with `make clickhouse-stop`.
|
|
|
|
Volumes are preserved. You'll find that the Postgres and Clickhouse state are retained when you bring them up again the next time: no need to re-register and so on.
|
|
|
|
Note: Since we are deleting the containers, be careful when deleting volumes with `docker volume prune`. You might accidentally delete the database and would have to go through re-registration process.
|
|
|
|
### Pre-commit hooks
|
|
|
|
`pre-commit` requires Python to be available locally and covers JavaScript and CSS. Set up with `pip install --user pre-commit` followed by `pre-commit install`. Conversely, if the prompts are far too bothersome, remove with `pre-commit uninstall`.
|