⚠️ This repository has been discontinued. It was once created as a personal replacement to DockSTARTER but I have since then moved on to more automation layers, such as ansible.
dockr is CLI tool for managing docker-compose files, currently building on Ubuntu/Debian.
The goal of dockr is to help you administer docker-compose and your container config files in a easy and predictable way. It's main purpose is to find compose.yaml-files in the config/**/ directory, verify their syntax, and merge them into one to run with docker-compose.
You may use this tool how you like. In the end, it's just merging your docker-compose files into one, and can optionally use global and app specific environment variables.
Please note that this project is under development. While it's being used in small production, do not use this in your production environment until you feel comfortable.
- Dockr
- Features
- Getting started
- Verify installation
- Create an app
- Use Dockr
- Environment
- Use Dockr using container (experimental)
- Contribute
- One-line installation and setup
- Easily create a new dockr app from a template using
dockr run [app] - Environment variables templating in
compose.yamlfiles - Verify, merge and docker-compose up using
dockr run - Easy update to latest version of dockr using
dockr update
This one-line installation currently building on Ubuntu/Debian using apt as package manager.
Before you start the installation, make sure that git, node and docker is installed.
As a general note, never trust installation scripts from unknown sources. This includes this project and repository. If you want to inspect the installation scripts, broadly see install.sh and setup.sh. You may also check out the latest builds to see what to expect.
wget -Nnv https://raw.githubusercontent.com/jeliasson/dockr/master/app/scripts/install.sh 2>&1 >/dev/null && bash install.shMake sure everything went fine by either running dockr or dockr info. You can also use the alias dr, e.g. dr info.
$ dockr
Usage: dockr [options] [command]
Options:
-V, --version output the version number
-h, --help output usage information
Commands:
run verify, merge and compose up
edit [app] edit app composer.yaml
logs [app] dockr logs, or dockr app logs
create [app] create a new app with boilerplates
compose [cmd] docker-compose wrapper
backup make a backup of dockr
config cd to dockr config directory
info info about the dockr installation
logs [app] dockr logs, or dockr app logs
update update dockr
verify verify syntax of all yaml files
test test docker-compose files
clean clean temporary generated files
help this help section
help [cmd] display help for [cmd]
In dockr, a directory in config/ is refered as in app, e.g. app portainer will reside in config/portainer. To create an app, run docker create <app>.
The generated docker-compose file config/<app>/compose.yaml should contain your normal docker-compose directives, and you can use environment variables in these directives.
Running dockr run will verify, merge and docker-compose up your apps, e.g.
$ dr run
ℹ Finding yaml files in config directory...
- Processing dockr-hello
- Processing portainer
✔ Merge of files completed.
ℹ Running docker-compose...
dockr-hello is up-to-date
portainer is up-to-dateIn above example, both images were already built and running.
Generated docker-compose file will be placed in the root path of dockr, by default ~/dockr/docker-compose.yaml.
dockr run will effectively run docker-compose -f ~/docker/docker-compose.yaml -d --remove-orphans up once app yaml files has been parsed.
By passing --remove-orphans, docker will delete containers that have been removed from the same docker compose stack. In this case, containers that has been created using dockr. It will not delete containers you've created outside of dockr.
During dockr run, when generating app docker-compose files, dockr will bring envioronment runtime such as app environment variabels and global environment variabels and have them merged with placeholders in respective compose.yaml file.
Environment variables is defined in the .env file in your app directory. If you created the app using dockr run, this file has been created for you. Example syntax that would set environment variable PORT to value 8080.
PORT=8080These environment variables may be used in compose.yaml files, e.g. ${{PORT}} would result in 8080.
It's recommended to use globally defined and generated environment variables, such as ${{DATA_DIR}}, that would return the absolute data path to the app during merge.
| Scope | Variable | Value | Description |
|---|---|---|---|
| Global | PUID |
1000 |
Default system user id to run docker containers. |
| Global | PGID |
1000 |
Default system group id to run docker containers. |
| Global | DOCKR_APP_NAME |
[app] |
App name during merge process of yaml files |
| Global | DOCKR_APP_PATH |
/[...]/config/[app] |
Absolute app path during merge process of yaml files |
| Global | DOCKR_DATA_PATH |
/[...]/dockr/config/<app>/data |
Absolute path to apps data directory |
| Global | DOCKR_DISABLED |
<not set> |
Disables parse of app's compose.yaml if env set |
| Global | TZ |
Europe/Malta |
Timezone |
| App | PORT |
8080 |
Example described in App variables. |
Working on having the dockr command wrapped to run the dockr image, and the end result would be to use dockr without installing any dependencies locally, besides docker of course.
Before the image is stable and ready for having an alias for dockr, we'll build the image and run it manually.
cd ~/docker
docker build -t dockr app
docker run -v config:/config dockr info
cd ~/dockr
docker-compose --remove-orphans -f ./app/docker-compose.yaml up
Feel free to fork and send a Pull Request if you see something that can be made better. ❤️
To setup your development dockr, run sh ./app/scripts/install-dev.sh. What's different between the original installation script is basically checking out the dev-branch