Skip to content

Linux (recommended)

These instructions are intended for the person who administers the instance, usually a more technical/operational profile.

Prerequisites (Ubuntu)

  1. Install dependencies:
sudo apt update && sudo apt install -y git docker.io docker-compose-plugin
  1. Add your user to the Docker group:
sudo usermod -aG docker $USER
  1. Log out and log back in to apply the group permission.

Note:

  • If you do not have root permissions, use sudo when necessary.

Installation

  1. Download the repository and enter the folder:
git clone https://gitlab.com/yndexa/farinha.git
cd farinha
  1. Start Farinha:
./run.sh

On the first run, run.sh:

  • creates the .env file automatically from .env-sample;
  • asks for the public Farinha address (in Portuguese and English). If you do not know it yet, press Enter to leave it blank and continue; you can edit .env later;
  • generates a safe SECRET_KEY, without requiring Django to be installed on the server;
  • creates an admin user with a random password, shown on the console only once. Write down the password before closing the terminal.

The automatic key does not contain $. If you create a SECRET_KEY manually and it contains $, the script warns that Docker Compose may interpret this character as an environment variable and offers to generate a new safe key.

To determine which environment will be used (development or production), the script reads the ENV variable from .env. .env-sample ships with ENV=prod and DEBUG=False, which are appropriate values for a real installation.

HTTPS and certificates

Farinha uses Caddy to serve HTTPS:

  • With a public address configured, free certificates are obtained and renewed automatically.
  • To use your own certificates, place fullchain.pem and privkey.pem in the certs/ folder at the project root.
  • Without a public address and without your own certificates (for example, localhost), HTTPS is disabled automatically.

See the details in Security and HTTPS, including the DISABLE_HTTPS variable and bot protection (Anubis).

Optional manual adjustment

If you need to review or change settings, open .env with your preferred text editor:

nano .env

Updating

  1. Enter the folder where Farinha was installed:
cd farinha
  1. Stop, update, and start again:
./down.sh && git pull && ./run.sh

Good practices

  • Write down the admin user password shown on the first run; it is not displayed again.
  • Keep DEBUG=False in .env in real installations.
  • Back up the database (db/) before updates and keep the certs/ folder if you use your own certificates.
  • Prefer updating by stopping and starting everything again (down + pull + run), rather than recreating a single container.

Common problems

  • “permission denied” when using Docker: your user is not in the Docker group. Run sudo usermod -aG docker $USER and log out/log back in (or use sudo, when appropriate).
  • The script stops without starting: check that SECRET_KEY is present in .env and does not contain $.
  • I lost the admin user password: create another superuser from the terminal, inside the container:
docker compose -f docker-compose.prod.yml exec web python manage.py createsuperuser
  • I can only access via HTTP: with localhost or an IP, HTTPS is disabled; configure a domain or your own certificates. See Security and HTTPS.
  • The internal panel does not open at /admin/: someone may have changed ADMIN_PATH in .env. See SuperAdmin user.