<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="ie=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="ExDoc v0.30.3">
    <meta name="project" content="Plausible v0.0.1">

    <title>Contributing — Plausible v0.0.1</title>
    <link rel="stylesheet" href="dist/html-elixir-P5GXSCHE.css" />


    <script src="dist/handlebars.runtime-NWIB6V2M.js"></script>
    <script src="dist/handlebars.templates-NBND3S2D.js"></script>
    <script src="dist/sidebar_items-AC4564C4.js"></script>

      <script src="docs_config.js"></script>

    <script async src="dist/html-CGDDOCMI.js"></script>


  </head>
  <body data-type="extras" class="page-extra">
    <script>

      try {
        var settings = JSON.parse(localStorage.getItem('ex_doc:settings') || '{}');

        if (settings.theme === 'dark' ||
           ((settings.theme === 'system' || settings.theme == null) &&
             window.matchMedia('(prefers-color-scheme: dark)').matches)
           ) {
          document.body.classList.add('dark')
        }
      } catch (error) { }
    </script>

<div class="main">

<button class="sidebar-button sidebar-toggle" aria-label="toggle sidebar">
  <i class="ri-menu-line ri-lg" title="Collapse/expand sidebar"></i>
</button>

<section class="sidebar">
  <form class="sidebar-search" action="search.html">
    <button type="submit" class="search-button" aria-label="Submit Search">
      <i class="ri-search-2-line" aria-hidden="true" title="Submit search"></i>
    </button>
    <button type="button" tabindex="-1" class="search-close-button" aria-label="Cancel Search">
      <i class="ri-close-line ri-lg" aria-hidden="true" title="Cancel search"></i>
    </button>
    <label class="search-label">
      <p class="sr-only">Search</p>
      <input name="q" type="text" class="search-input" placeholder="Search..." aria-label="Input your search terms" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" />
    </label>
  </form>

  <div class="autocomplete">
    <div class="autocomplete-results">
    </div>
  </div>

  <div class="sidebar-header">

      <a href="readme.html">
        <img src="assets/logo.png" alt="Plausible" class="sidebar-projectImage">
      </a>

    <div class="sidebar-projectDetails">
      <a href="readme.html" class="sidebar-projectName" translate="no">
Plausible
      </a>
      <div class="sidebar-projectVersion" translate="no">
        v0.0.1
      </div>
    </div>
    <ul class="sidebar-listNav">
      <li><a id="extras-list-link" href="#full-list">Pages</a></li>

        <li><a id="modules-list-link" href="#full-list">Modules</a></li>


        <li><a id="tasks-list-link" href="#full-list"><span translate="no">Mix</span> Tasks</a></li>

    </ul>
  </div>

  <div class="gradient"></div>
  <ul id="full-list"></ul>
</section>

<section class="content">
  <output role="status" id="toast"></output>
  <div class="content-outer">
    <div id="content" class="content-inner">

<h1>
<button class="icon-action display-settings">
  <i class="ri-settings-3-line"></i>
  <span class="sr-only">Settings</span>
</button>


    <a href="https://github.com/plausible/analytics/blob/main/CONTRIBUTING.md#L1" title="View Source" class="icon-action" rel="help">
      <i class="ri-code-s-slash-line" aria-hidden="true"></i>
      <span class="sr-only">View Source</span>
    </a>


  <span>Contributing</span>
</h1>

<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><h2 id="development-setup" class="section-heading">
  <a href="#development-setup">
    <i class="ri-link-m" aria-hidden="true"></i>
    Development setup
  </a>
</h2>
<p>The easiest way to get up and running is to <a href="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 <a href="https://github.com/plausible/analytics/blob/master/.tool-versions"><code class="inline">.tool-versions</code></a> file is available to use with <a href="https://github.com/asdf-vm/asdf">asdf</a> or similar tools.</p><h3 id="start-the-environment" class="section-heading">
  <a href="#start-the-environment">
    <i class="ri-link-m" aria-hidden="true"></i>
    Start the environment
  </a>
</h3>
<ol><li>Run both <code class="inline">make postgres</code> and <code class="inline">make clickhouse</code>.</li><li>You can set up everything with <code class="inline">make install</code>, alternatively run each command separately:<ol><li>Run <a href="https://hexdocs.pm/mix/Mix.Tasks.Deps.Get.html"><code class="inline">mix deps.get</code></a>. This will download the required Elixir dependencies.</li><li>Run <a href="https://hexdocs.pm/ecto/3.10.3/Mix.Tasks.Ecto.Create.html"><code class="inline">mix ecto.create</code></a>. This will create the required databases in both Postgres and Clickhouse.</li><li>Run <a href="https://hexdocs.pm/ecto_sql/3.10.1/Mix.Tasks.Ecto.Migrate.html"><code class="inline">mix ecto.migrate</code></a> to build the database schema.</li><li>Run <code class="inline">mix run priv/repo/seeds.exs</code> to seed the database. Check the <a href="#Seeds">Seeds</a> section for more.</li><li>Run <code class="inline">npm ci --prefix assets</code> to install the required client-side dependencies.</li><li>Run <code class="inline">npm ci --prefix tracker</code> to install the required tracker dependencies.</li><li>Run <code class="inline">npm run deploy --prefix tracker</code> to generate tracker files in <code class="inline">priv/tracker/js</code></li><li>Run <code class="inline">mix download_country_database</code> to fetch geolocation database</li></ol></li><li>Run <code class="inline">make server</code> or <a href="https://hexdocs.pm/phoenix/1.7.7/Mix.Tasks.Phx.Server.html"><code class="inline">mix phx.server</code></a> to start the Phoenix server.</li><li>The system is now available on <code class="inline">localhost:8000</code>.</li></ol><h3 id="seeds" class="section-heading">
  <a href="#seeds">
    <i class="ri-link-m" aria-hidden="true"></i>
    Seeds
  </a>
</h3>
<p>You can optionally seed your database to automatically create an account and a site with stats:</p><ol><li>Run <code class="inline">mix run priv/repo/seeds.exs</code> to seed the database.</li><li>Start the server with <code class="inline">make server</code> and navigate to <code class="inline">http://localhost:8000/login</code>.</li><li>Log in with the following e-mail and password combination: <code class="inline">user@plausible.test</code> and <code class="inline">plausible</code>.</li><li>You should now have a <code class="inline">dummy.site</code> site with generated stats.</li></ol><p>Alternatively, you can manually create a new account:</p><ol><li>Navigate to <code class="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 <code class="inline">dummy.site</code></li><li>Skip the JS snippet and click start collecting data.</li><li>Run <code class="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><h3 id="stopping-docker-containers" class="section-heading">
  <a href="#stopping-docker-containers">
    <i class="ri-link-m" aria-hidden="true"></i>
    Stopping Docker containers
  </a>
</h3>
<ol><li>Stop and remove the Postgres container with <code class="inline">make postgres-stop</code>.</li><li>Stop and remove the Clickhouse container with <code class="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 <code class="inline">docker volume prune</code>. You might accidentally delete the database and would have to go through re-registration process.</p><h3 id="pre-commit-hooks" class="section-heading">
  <a href="#pre-commit-hooks">
    <i class="ri-link-m" aria-hidden="true"></i>
    Pre-commit hooks
  </a>
</h3>
<p><code class="inline">pre-commit</code> requires Python to be available locally and covers Elixir, JavaScript, and CSS. Set up with <code class="inline">pip install --user pre-commit</code> followed by <code class="inline">pre-commit install</code>. Conversely, if the prompts are far too bothersome, remove with <code class="inline">pre-commit uninstall</code>.</p><h2 id="finding-a-task" class="section-heading">
  <a href="#finding-a-task">
    <i class="ri-link-m" aria-hidden="true"></i>
    Finding a task
  </a>
</h2>
<p>Bugs can be found in our <a href="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 <a href="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>
<div class="bottom-actions">
  <div class="bottom-actions-item">

      <a href="readme.html" class="bottom-actions-button" rel="prev">
        <span class="subheader">
          ← Previous Page
        </span>
        <span class="title">
Introduction
        </span>
      </a>

  </div>
  <div class="bottom-actions-item">

      <a href="account-locking.html" class="bottom-actions-button" rel="next">
        <span class="subheader">
          Next Page →
        </span>
        <span class="title">
Account locking
        </span>
      </a>

  </div>
</div>
      <footer class="footer">
        <p>

          <span class="line">
            <button class="a-main footer-button display-quick-switch" title="Search HexDocs packages">
              Search HexDocs
            </button>

              <a href="Plausible.epub" title="ePub version">
                Download ePub version
              </a>

          </span>
        </p>

        <p class="built-using">
          Built using
          <a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener" translate="no">ExDoc</a> (v0.30.3) for the

            <a href="https://elixir-lang.org" title="Elixir" target="_blank" translate="no">Elixir programming language</a>

        </p>
      </footer>
    </div>
  </div>
</section>
</div>

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad: true})</script>

  </body>
</html>