We welcome everyone to contribute to Plausible. This document is to help you on setting up your environment, finding a task, and opening pull requests.
The easiest way to get up and running is to install and use Docker for running both Postgres and Clickhouse.
Make sure Docker, Elixir, Erlang and Node.js are all installed on your development machine. The .tool-versions
file is available to use with asdf or similar tools.
make postgres
and make clickhouse
.make install
, alternatively run each command separately:
mix deps.get
. This will download the required Elixir dependencies.mix ecto.create
. This will create the required databases in both Postgres and Clickhouse.mix ecto.migrate
to build the database schema.mix run priv/repo/seeds.exs
to seed the database. Check the Seeds section for more.npm ci --prefix assets
to install the required client-side dependencies.npm ci --prefix tracker
to install the required tracker dependencies.mix assets.setup
to install Tailwind and Esbuildnpm run deploy --prefix tracker
to generate tracker files in priv/tracker/js
mix download_country_database
to fetch geolocation databasemake server
or mix phx.server
to start the Phoenix server.localhost:8000
.You can optionally seed your database to automatically create an account and a site with stats:
mix run priv/repo/seeds.exs
to seed the database.make server
and navigate to http://localhost:8000/login
.user@plausible.test
and plausible
.dummy.site
site with generated stats.Alternatively, you can manually create a new account:
http://localhost:8000/register
and fill in the form.dummy.site
mix send_pageview
from the terminal to generate a fake pageview event for the dummy site.make postgres-stop
.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
requires Python to be available locally and covers Elixir, 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
.
Bugs can be found in our issue tracker. Issues are usually up for grabs.
New features need to be discussed with the core team and the community first. If you're tackling a feature, please make sure it has been already discussed in the Discussions tab. We kindly ask contributors to use the discussion comment section to propose a solution before opening a pull request.
Pull requests without an associated issue or discussion may still be merged, but we will focus on changes that have already been talked through.