Contributing to PiGuard v2 Web Portal

This page is a guide for both users and developers willing to contribute.

Table of Content

Reporting a bug

Ensure the issue you're about to submit isn't a duplicate. Then, open a new issue using the appropriate template.

Requesting new features or discussing the project

Ensure the issue you're about to submit isn't a duplicate. Then, open a new issue using the appropriate template.

Writing code

If you want to submit a fix or propose a new feature, follow the guidelines below.

Prerequisites

  • PiGuard installed on a Raspberry Pi with SSH access and a user with sudo permissions.

Raspberry Pi prerequisites

The following dependencies must be installed on the Raspberry Pi:

  • GNU make
  • Wireguard
  • Python >=3.10
  • Poetry

Installation

1. Clone or copy the repository on the Raspberry Pi and change it to your working directory.

2. Install the project:

$ poetry install

3. 💡 Optional: If you want to create the virtual environment in a .venv folder inside the project's directory, run:

$ poetry config virtualenvs.in-project true

Existing configuration options can be listed as follows:

$ poetry config --list

Activate the Python virtual environment:

$ poetry shell

4. Set the .env file with the following environment variables:

# Key used for checking and signing cookies.
PIGUARD_SECRET_KEY=
# The username to sign in.
PIGUARD_USERNAME=
# Hash of the password used to sign in.
PIGUARD_PASSWORD_HASH=
# Absolute path to the WireGuard file (contains the keys).
PIGUARD_WIREGUARD_FILE='/etc/wireguard/wg0.conf'
# Absolute path to the hostapd file (contains the network credentials).
PIGUARD_HOSTAPD_FILE='/etc/hostapd/hostapd.conf'

For local development, here are some tips to create dummy values:

  • To generate a key for PIGUARD_SECRET_KEY, run the following command in your terminal:
python -c 'import secrets; print(secrets.token_hex())'
  • To generate a hashed password for PIGUARD_PASSWORD_HASH, run the following commands in a Python console:
>>> from werkzeug.security import generate_password_hash
>>> generate_password_hash('YOUR_PASSWORD')
'pbkdf2:sha256:600000$........'
  • You can find dummy hostapd and wg.conf files here.

5. Run the application:

$ make debug

Format and lint code

Install the pre-commit hooks by running:

$ pre-commit install

Formatting and linting tools will run before each commit.

Commit Message format

Commit messages should follow this format:

<type>([optional scope]): <description>

Example:

fix(login): Set password

💡 Find more information here.

Branch Naming

Branch names should follow this format:

<type>/<short-description>

Example:

feature/send_pub_key

Submitting Changes

  1. Create a new branch based on the dev branch (TODO: Update for main branch).

  2. Write your code.

  3. Ensure you activated the virtual environment and activated the Python pre-commit hooks. A pre-commit hook should run before each commit. Commit your changes following the commit message format.

  4. Pull from Upstream: Before pushing your changes, pull the latest changes from the upstream dev branch:

git pull upstream dev

  1. Push your work.

  2. Open a merge request.

Improving documentation

Prerequisites

Installation

Assuming you cloned the repository, install dependencies and activate the virtual environment as follows:

$ poetry install
$ poetry shell

Writing documentation pages

1. Create a new branch based on the dev branch (TODO: Update for main branch). It will be named as follows: docs/<your_changes>

2. The documentation is created using MkDocs. Thus, the documentation pages are Markdown files placed in the docs directory. Modify, delete or add any Markdown file you want.

3. Don't forget to add any new page to the navigation bar. To do so, update the mkdocs.yml file at the root of the repository.

4. If you want to preview the documentation locally, build and serve the documentation:

$ make docs

Then, open up http://127.0.0.1:8000/ in your browser.

5. Commit your changes.

6. Pull from Upstream: Before pushing your changes, pull the latest changes from the upstream dev branch (TODO: Update for main branch):

$ git pull upstream dev

7. Push your work.

8. Open a merge request. Make sure to tag the maintainers in order to get a review.