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.
Using AppJail Director is a three-step process:
- Define your app's environment with a
Makejailso it can be reproduced anywhere. - Define the services that make up your app in
appjail-director.ymlso they can be run together in an isolated environment. - Lastly, run
appjail-director upand 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: ./appdataBleeding-edge version:
pkg install -y py311-pipx
pipx install git+https://github.com/DtxdF/director.git
appjail-director --helpNote: Remember to add ~/.local/bin to PATH.
Stable version:
pkg install -y py311-directorAppJail must be installed before using Director.
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.
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.
Read more details in appjail-director --help about which configuration files are used and how they are loaded.
type: String.
default: ~/.director/logs.
description: Directory where the logs will be stored.
type: String.
default: ~/.director/projects.
description: Directory where the projects and its metadata will be stored.
type: Boolean.
default: false.
description: Only valid for ZFS. Recursively removes the jail and its references.
type: Boolean.
default: true.
description: Only valid for ZFS. Forcibly removes the jail dataset.
type: Integer.
default: 1800.
description: Timeout to avoid hangings caused by some operations such as the execution of Makejail or some custom commands in your Director file.
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: ./appdataInstead 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
type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.
description: Options that will be used by all services.
type: Dictionary.
description: This dictionary contains the services to be created and started. Each key is the name of the service that must be valid with the following regular expression: ^[a-zA-Z0-9._-]+$. The name of the service is not the same as the name of the jail.
type: Integer.
default: 99.
description: Once the Director file has been processed, the services will be sorted using this number. Lower integers have higher priority, so those services will be processed first.
type: String.
description: Jail name. If not specified, a random hexadecimal string will be used.
type: String.
default: Makejail
description: Makejail to be executed.
type: Boolean.
description: The global options will be added to the local options. These options only take into account the local options per service.
type: Boolean.
description: Do not recreate the service when the Makejail modification time changes.
It has the same effect as the global options, but only for the services in which it appears.
type: Array of dictionaries. Each dictionary (key and value) is a string.
description: Arguments to pass to the Makejail to be executed.
type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.
description: Environment variables valid only in the build stage.
type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.
description: Environment variables valid only in the start stage.
type: Dictionary.
description: Settings used by OCI-related commands.
type: String.
description: Execute the process specified by the OCI image as another user.
type: String.
description: Execute the process specified by the OCI image in this working directory.
type: Array of dictionaries. Each dictionary (key and value) is a string. The value can be left empty.
description: Environment variables used by the process specified by the OCI image.
type: Array of dictionaries. Each dictionary (key and value) is a string.
description: The key of each dictionary is used to obtain the volume options specified by the global volumes.
type: Array of dictionaries.
description: Scripts that will be executed once the jail is created and started.
type: String.
default: /bin/sh -c
description: Shell used to execute the script.
type: String.
default: jexec
options: jexec, local and chroot.
description: In which environment the script will be executed.
type: String.
description: Script to be executed.
type: Array of dictionaries. Each dictionary (key and value) is a string.
description: Arguments to be passed to the start stage.
type: Integer.
default: 0.
description: Director detects changes to re-run the Makejail, this item forces the execution of the Makejail.
type: String.
description: Default volume type when type is not defined in volumes/{volume}.
type: Dictionary.
description: Describe the volume options used by the services.
type: String.
description: Device to be mounted.
type: String.
default: <pseudofs>.
description: Type of the file system. When using nullfs, <pseudofs> or <volumefs>, device is treated as a directory and after getting the absolute path it will be used as the actual device.
See AppJail#pseudofs for more details about the pseudo-filesystem.
type: String.
default: rw.
description: Mount point options associated with the file system.
type: Integer.
default: 0.
description: It is used for these file systems by the dump(8) command to determine which file systems need to be dumped.
type: Integer.
default: 0.
description: It is used by the fsck(8) and quotacheck(8) programs to determine the order in which file system and quota checks are done at reboot time.
type: Integer.
description: Valid only for nullfs, <pseudofs> and <volumefs> file systems. When defined the umask is set before the creation of the directory (aka device) and is restored after the directory is created.
type: Integer.
description: Valid only for nullfs, <pseudofs> and <volumefs> file systems. Change the access permissions of the directory (aka device) after its creation.
type: Integer or String.
description: Valid only for nullfs, <pseudofs> and <volumefs> file systems. When defined the directory owner is set after the creation of the directory (aka device). Note that if you use a string instead of an integer, it will be resolved from your local user database.
It has the same effect as owner, but for the device group.
GIT_ASKPASSenvironment variable is set totrueto avoid hangings caused bygit(1).
If you have found a bug, have an idea or need help, use the issue tracker. Of course, PRs are welcome.