AppJail Director

AppJail Director is a tool for running multi-jail environments on AppJail using a simple YAML specification. A Director file is used to define how one or more jails that make up your application are configured. Once you have a Director file, you can create and start your application with a single command: appjail-director up.

Quick Start

Using AppJail Director is a three-step process:

1. Define your app's environment with a Makejail so it can be reproduced anywhere.
2. Define the services that make up your app in appjail-director.yml so they can be run together in an isolated environment.
3. Lastly, run appjail-director up and Director will start and run your entire app.

A Director file looks like this:

options:
  - virtualnet: ':<random> default'
  - nat:
services:
  web:
    makejail: Makejail
    options:
      - expose: 5000
    volumes:
      - appdata: /app/data
  mariadb:
    makejail: gh+AppJail-makejails/mariadb
    arguments:
      - mariadb_user: 'example-user'
      - mariadb_password: 'my_cool_secret'
      - mariadb_database: 'appdb'
      - mariadb_root_password: 'my-secret-pw'
volumes:
  appdata:
    device: ./appdata

Installation

Bleeding-edge version:

pkg install -y py311-pipx
pipx install git+https://github.com/DtxdF/director.git
appjail-director --help

Note: Remember to add ~/.local/bin to PATH.

Stable version:

pkg install -y py311-director

AppJail must be installed before using Director.

Note about non-root users

If you want to run Director with a non-root user, you must configure AppJail to do so.

By default, ~/.director is used as the base directory, so every file generated by Director will belong to you.

Ephemeral concept

Director treats each jail as ephemeral. This does not mean that your jails will not persist after you stop them or restart your system, what it means is that Director assumes that it is safe to destroy the jails since you have clearly separated the data that should be persisted from the data considered ephemeral.

Environment

You can use environment variables within the Director file:

options:
  - virtualnet: ':<random> default'
  - nat:
services:
  web:
    makejail: Makejail
    options:
      - expose: 5000
    volumes:
      - appdata: /app/data
  mariadb:
    makejail: gh+AppJail-makejails/mariadb
    arguments:
      - mariadb_user: !ENV '${DB_USER}'
      - mariadb_password: !ENV '${DB_PASS}'
      - mariadb_database: !ENV '${DB_NAME:appdb}'
      - mariadb_root_password: !ENV '${DB_ROOT_PASS}'
volumes:
  appdata:
    device: ./appdata

Instead of setting each environment variable from the command line, you can use a .env file:

.env:

DIRECTOR_PROJECT=myapp
DB_USER=example-user
DB_PASS=my_cool_secret
DB_NAME=appdb
DB_ROOT_PASS=my-secret-pw

Documentation

• man 1 director
• man 5 director-spec

Notes

• GIT_ASKPASS environment variable is set to true to avoid hangings caused by git(1).

Contributing

If you have found a bug, have an idea or need help, use the issue tracker. Of course, PRs are welcome.