Hosting

Getting support

This application is designed to be self-hosted. If you are a community or organization that wants to host this application, feel free to contact IDA (gruppe_arbeitszeit@riseup.net) for help.

For general information on deploying a Flask application see the Flask deployment documentation.

NixOS Deployment

The IDA github organization maintains a repository with a NixOS module for deployment on NixOS servers: https://github.com/ida-arbeitszeit/workers-control-deployment.

PyPi

The app is available on PyPi. Try it out:

pip install workers-control
flask --app workers_control.flask.wsgi:app run

Configuration of the web server

For the app to work properly, the web server needs to be configured with environment variables and a Python configuration file.

Environment variables

WOCO_CONFIGURATION_PATH

(optional)

If set, this value is used as the path to the configuration file (see below) instead of the default locations.

Configuration file

The application loads the first config file found from these locations:

• Path set in WOCO_CONFIGURATION_PATH environment variable (see above)

• /etc/workers-control/workers-control.py

The configuration file must be a valid python script. Configuration options are set as top-level variables. The following options are available (options without defaults are required):

DEFAULT_USER_TIMEZONE

The default timezone for users. This must be a valid timezone string as found in the tz database.

Example: DEFAULT_USER_TIMEZONE = "Europe/Berlin"

Default: "UTC"

AUTO_MIGRATE

Upgrade the database schema if changes are detected on startup. If auto migration is not activated, you need to run database migrations manually.

Example: AUTO_MIGRATE = True

Default: False

FORCE_HTTPS

This option controls whether the application will allow unsecure HTTP trafic or force a redirect to an HTTPS address.

Example: FORCE_HTTPS = False

Default: True

MAIL_SERVER

The hostname of the SMTP server used for sending emails.

MAIL_PORT

The port number of the SMTP server used for sending emails.

Default: 587

MAIL_USERNAME

The username used to authenticate with the SMTP server.

MAIL_PASSWORD

The password used to authenticate with the SMTP server.

MAIL_DEFAULT_SENDER

The sender address used for outgoing emails.

MAIL_ADMIN

The email address of the administrator for the application. Users may use this email address to contact the administrator.

MAIL_ENCRYPTION_TYPE

Which encryption should be used when connecting to the SMTP server. Must be either ‘tls’ or ‘ssl’.

Default: tls

SECRET_KEY

A long, random secret value used by the application to cryptographically sign user sessions, CSRF tokens, and security-relevant tokens such as password-reset and email-confirmation links. Setting this option is obligatory. Keep it secret; if it leaks, rotate it.

SECURITY_PASSWORD_SALT

A secret value used together with SECRET_KEY to sign security tokens (password-reset and email-confirmation links). Despite its name, it is not used to hash user passwords. Changing or losing it invalidates any tokens that have already been issued but not yet redeemed; it does not affect stored passwords.

SERVER_NAME

This variable tells the application how it is addressed. This is important to generate links in emails it sends out.

Example: SERVER_NAME = "workers-control.cp.org"

SQLALCHEMY_DATABASE_URI

The address of the database used for persistence. The application has been tested with PostgreSQL and SQLite databases.

Example: SQLALCHEMY_DATABASE_URI = "postgresql:///my_data"

Default: "sqlite:////tmp/workers_control.db"

ALLOWED_OVERDRAW_MEMBER

The maximum allowed overdraw limit for members in hours (integer). Set to unlimited to allow unlimited overdraw.

Default: 0

ACCEPTABLE_RELATIVE_ACCOUNT_DEVIATION

This integer defines the “relative deviation” from the ideal account balance of zero that is still deemed acceptable, expressed in percent and calculated relative to the expected transfer value of this account.

Example: Company XY has an absolute deviation of minus 1000 hours on its account for means of production (PRD account). Because it has filed plans with total costs for means of production of 10000 hours (=the sum of expected transfer value), its relative deviation is 10%.

Unacceptable high deviations might get labeled as such or highlighted by the application.

Default: 33

PAYOUT_FACTOR_CALCULATION_WINDOW

A time window in days, over which the payout factor is calculated.

Must be an integer larger than zero.

Default: 180

ALEMBIC_CONFIG

Path to a custom alembic configuration file. Alembic is used to manage database migrations. See the Alembic documentation for details.

If not set, the bundled alembic.ini from the installed package is used.

Example: ALEMBIC_CONFIG = "/some/path/to/alembic.ini"

Default: <path to bundled alembic.ini>

Inviting accountants

To invite an accountant, use the invite-accountant CLI command with the accountant’s email address:

flask --app workers_control.flask.wsgi:app invite-accountant example@mail.de

This sends an email with a registration link to the given address.

Email sending worker

Outbound email is delivered asynchronously by a separate worker process. The Flask app writes outbound messages to an email_outbox database table inside the same transaction as the data change that triggered them (transactional outbox pattern). A long-running worker polls that table, sends each message via SMTP, and records success or failure on the row.

Run the worker with:

flask --app workers_control.flask.wsgi:app send-emails

The worker should be supervised so that it is restarted automatically. A minimal systemd service unit looks like this:

[Unit]
Description=Workers Control email sending worker
After=network.target

[Service]
Type=simple
Environment=WOCO_CONFIGURATION_PATH=/etc/workers-control/workers-control.py
ExecStart=/usr/bin/flask --app workers_control.flask.wsgi:app send-emails
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Without a running worker, mail accumulates in the email_outbox table but is never delivered.

The worker’s delivery backend is selected via the MAIL_SENDER_PLUGIN configuration option. The default, workers_control.email_sending_worker.smtp_service:SmtpMailService, delivers via SMTP using the standard MAIL_SERVER, MAIL_PORT, MAIL_ENCRYPTION_TYPE, MAIL_USERNAME and MAIL_PASSWORD settings. You normally do not need to change this; it exists so that development and test environments can substitute a non-SMTP backend that simply logs each message.