Docker templates

Reusable, security-hardened Compose stacks. An app is one directory at the repository root. A shared service lives once under templates/<service>/. run.sh <AppDir> merges that app with the services named in x-required-services.

app_template/ and templates/template/ are the references. Copy one before the first real deployment. The reference app still contains placeholders, so run.sh app_template stops until those names are replaced. Details for a copied app are in app_template/README.md. Details for a new service template are in templates/template/README.md. Conventions live in .openso/rules/.

Requirements

Bash, Docker Compose v2, mikefarah yq v4, rsync, envsubst (gettext), and flock. get-folder.sh also needs Git. run.sh needs Git only when it has to clone templates because templates/ is not beside the script.

The scripts do not install packages and do not download binaries.

The default repository is private. A clone without stored Git credentials fails and prints these commands. Run them once on the machine. At the prompt, use your Forgejo username and a read-only token. Git stores that token. The scripts do not.

git config --global credential.helper store
git ls-remote https://git.openso.de/openso/docker-templates.git

Merge an app

From the repository root:

./run.sh <AppDir>

The first run renames the app .env to app.env when app.env does not exist yet. app.env is the file to edit. .env and docker-compose.main.yaml are regenerated on each run. Put values that must replace a template default in the OVERWRITES section of app.env.

When templates/ sits beside run.sh, that directory is the template source. A newer git revision is reported and applied with --force. Without a local templates/ directory, run.sh clones https://git.openso.de/openso/docker-templates.git at branch main. Before that clone, a deployed run.sh replaces itself when the branch tip is newer and the script content changed, then restarts the same command. The same run reports a newer app compose file, env file, or script and leaves it in place until --force. --force backs up a newer compose file or script, then replaces that file. For app.env, --force applies repository changes, including comments and removed keys, and leaves values edited in that file. The generated .env is rebuilt from that file. A git work tree is left unchanged. DOCKER_REPO_URL and DOCKER_REPO_BRANCH override that clone.

After a successful merge:

docker compose --env-file .env -f docker-compose.main.yaml up -d

Run that from the app directory. frontend and backend are external networks. Create the ones the app still joins before the first start. See app_template/README.md.

run.sh options

Option	Description
--force	Refresh templates. Rewrite app.env from the repository env file, including comments, added keys, and removed keys. Values edited in app.env stay. The generated .env is rebuilt from it. Replace newer app compose files and scripts. Replaced files are backed up to <AppDir>/.run.conf/.backups/ first. Running services are stopped while directory ownership is applied and started again afterwards, unless this run added an empty value or a CHANGE_ME placeholder to app.env or .env. Those keys are listed at the end of the run and the stack stays stopped.
--update	Pull images for the merged stack and recreate containers whose image changed.
--dry-run	Report the merge without publishing files.
--debug	Verbose logs.
--skip-permissions	Skip *_DIRECTORIES ownership on a normal run or --force.
--generate_password [FILE] [LENGTH]	Replace an exact CHANGE_ME secret. FILE is an UPPERCASE name. Length defaults to 100. Names in x-secret-generation-exclusions are left unchanged.
--check-logrotate	Read-only check of a declared host logrotate config.
--install-logrotate	Install or update that host config. Combine with --dry-run to preview.
--delete_volumes	Remove named volumes from the merged project.
-h, --help	Usage.

--force, --update, --delete_volumes, --generate_password, and the logrotate modes are mutually exclusive.

Logs are <AppDir>/.run.conf/logs/. The two newest files are kept.

Download one directory

get-folder.sh copies one repository directory into the current directory. Existing files under secrets/ are kept, including with --force. A missing placeholder is still copied. .gitkeep files are omitted. Local files that the repository no longer contains are left in place. Outside a git work tree it updates itself and run.sh when the repository tip is newer and that file changed. A locally edited script stays. --force still replaces run.sh. Inside a work tree, run.sh is copied only when it is absent or --force is set. A missing root run.sh is a warning.

chmod +x get-folder.sh
./get-folder.sh <AppDir>

Option	Description
--force	Refresh non-secret files and the root run.sh copy, even when the repository tip is not newer.
--dry-run	Read the repository and report each copy. The app directory is not written.
--debug	Verbose logs.
-h, --help	Usage.

DOCKER_REPO_URL overrides the source repository. DOCKER_REPO_BRANCH selects the branch name. The defaults are https://git.openso.de/openso/docker-templates.git and main. A second run exits while the first still holds the lock.

Developer setup

Enable the commit hook once per clone:

git config core.hooksPath .githooks

The hook runs the executable files in .openso/scripts/commit/. CI checks live in .forgejo/workflows/ci.yaml.