<p>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.</p><h2id="development-setup"class="section-heading">
<p>The easiest way to get up and running is to <ahref="https://docs.docker.com/get-docker/">install</a> and use Docker for running both Postgres and Clickhouse.</p><p>Make sure Docker, Elixir, Erlang and Node.js are all installed on your development machine. The <ahref="https://github.com/plausible/analytics/blob/master/.tool-versions"><codeclass="inline">.tool-versions</code></a> file is available to use with <ahref="https://github.com/asdf-vm/asdf">asdf</a> or similar tools.</p><h3id="start-the-environment"class="section-heading">
<ol><li>Run both <codeclass="inline">make postgres</code> and <codeclass="inline">make clickhouse</code>.</li><li>You can set up everything with <codeclass="inline">make install</code>, alternatively run each command separately:<ol><li>Run <ahref="https://hexdocs.pm/mix/Mix.Tasks.Deps.Get.html"><codeclass="inline">mix deps.get</code></a>. This will download the required Elixir dependencies.</li><li>Run <ahref="https://hexdocs.pm/ecto/3.11.1/Mix.Tasks.Ecto.Create.html"><codeclass="inline">mix ecto.create</code></a>. This will create the required databases in both Postgres and Clickhouse.</li><li>Run <ahref="https://hexdocs.pm/ecto_sql/3.11.1/Mix.Tasks.Ecto.Migrate.html"><codeclass="inline">mix ecto.migrate</code></a> to build the database schema.</li><li>Run <codeclass="inline">mix run priv/repo/seeds.exs</code> to seed the database. Check the <ahref="#Seeds">Seeds</a> section for more.</li><li>Run <codeclass="inline">npm ci --prefix assets</code> to install the required client-side dependencies.</li><li>Run <codeclass="inline">npm ci --prefix tracker</code> to install the required tracker dependencies.</li><li>Run <codeclass="inline">mix assets.setup</code> to install Tailwind and Esbuild</li><li>Run <codeclass="inline">npm run deploy --prefix tracker</code> to generate tracker files in <codeclass="inline">priv/tracker/js</code></li><li>Run <codeclass="inline">mix download_country_database</code> to fetch geolocation database</li></ol></li><li>Run <codeclass="inline">make server</code> or <ahref="https://hexdocs.pm/phoenix/1.7.10/Mix.Tasks.Phx.Server.html"><codeclass="inline">mix phx.server</code></a> to start the Phoenix server.</li><li>The system is now available on <codeclass="inline">localhost:8000</code>.</li></ol><h3id="seeds"class="section-heading">
<p>You can optionally seed your database to automatically create an account and a site with stats:</p><ol><li>Run <codeclass="inline">mix run priv/repo/seeds.exs</code> to seed the database.</li><li>Start the server with <codeclass="inline">make server</code> and navigate to <codeclass="inline">http://localhost:8000/login</code>.</li><li>Log in with the following e-mail and password combination: <codeclass="inline">user@plausible.test</code> and <codeclass="inline">plausible</code>.</li><li>You should now have a <codeclass="inline">dummy.site</code> site with generated stats.</li></ol><p>Alternatively, you can manually create a new account:</p><ol><li>Navigate to <codeclass="inline">http://localhost:8000/register</code> and fill in the form.</li><li>Fill in the rest of the forms and for the domain use <codeclass="inline">dummy.site</code></li><li>Skip the JS snippet and click start collecting data.</li><li>Run <codeclass="inline">mix send_pageview</code> from the terminal to generate a fake pageview event for the dummy site.</li><li>You should now be all set!</li></ol><h3id="stopping-docker-containers"class="section-heading">
<ol><li>Stop and remove the Postgres container with <codeclass="inline">make postgres-stop</code>.</li><li>Stop and remove the Clickhouse container with <codeclass="inline">make clickhouse-stop</code>.</li></ol><p>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.</p><p>Note: Since we are deleting the containers, be careful when deleting volumes with <codeclass="inline">docker volume prune</code>. You might accidentally delete the database and would have to go through re-registration process.</p><h3id="pre-commit-hooks"class="section-heading">
<p><codeclass="inline">pre-commit</code> requires Python to be available locally and covers Elixir, JavaScript, and CSS. Set up with <codeclass="inline">pip install --user pre-commit</code> followed by <codeclass="inline">pre-commit install</code>. Conversely, if the prompts are far too bothersome, remove with <codeclass="inline">pre-commit uninstall</code>.</p><h2id="finding-a-task"class="section-heading">
<p>Bugs can be found in our <ahref="https://github.com/plausible/analytics/issues">issue tracker</a>. Issues are usually up for grabs.</p><p>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 <ahref="https://github.com/plausible/analytics/discussions">Discussions tab</a>. We kindly ask contributors to use the discussion comment section to propose a solution before opening a pull request.</p><p>Pull requests without an associated issue or discussion may still be merged, but we will focus on changes that have already been talked through.</p>
