Software Freedom Lock

You will need Poetry.

Getting started

1. Copy the required files to start the server:

   $ cp .env.example .env
   $ cp users.example.json users.json
   $ cp contacts.example.json contacts.json
   

2. Update the values of .env and add your users to users.json. A default user jane is added with PIN code 1234.

3. Install the required dependencies.

   $ poetry install
   

Development

4. Start the server using the helper run_dev.py

   $ poetry run python run_dev.py
   

5. Access http://localhost:5000/

Deployment

4. Start the server using Gunicorn

   $ poetry run gunicorn -w 1 'software_freedom_lock:app' --bind=0.0.0.0:8042
   

   Note: Only deploy with one worker, the challenges are handled using a global variable. Given that the deployment is done with a Raspberry Pi Zero 2W, running with one worker is the only sound choice.

5. Configure the log rotation with logrotate or a similar tool.

6. Configure the reverse proxy if there's any, then access http://example.local:8042

Note: When deploying, consider using something like a systemd service alongside the bridge service.

Maintenance

Adding and removing users

Users are stored in the users.json file (or in the file at $USERS_JSON_PATH). The pin_hash is an Argon2 encoded hash. Argon2i, Argon2d, and Argon2id; 10 and 13 are supported.

You can generate user excerpts through the /request_user page. You may also generate the Argon2 hash of your PIN through the command line with the argon2 command (argon2 package in Debian).

# Replace PINCODE with your actual PIN code
$ echo -n "PINCODE" | argon2 $(openssl rand -hex 12) -e -id

You can update the users.json file on the fly. The file is reloaded before checking for /unlock and /challenge requests through the JsonUserManager.

Updating emergency contacts

Emergency contacts are stored in the contacts.json file (or in the file at $CONTACTS_JSON_PATH).

The contacts cannot be updated on the fly, they are loaded on startup.