Madock configuration can be stored either globally or within a project folder.
~/.madock/
├── config.xml # Global settings
└── projects/
└── {project_name}/
├── config.xml # Project-specific settings
└── backup/
└── db/ # Database backups
{project_root}/
└── .madock/
├── config.xml # Project settings (version controlled)
├── backup/
│ └── db/ # Database backups
└── docker/ # Custom Docker overrides
- Create the
.madockfolder in your project root:
mkdir -p .madock- Create or copy
config.xmlwith the settings you want:
cp ~/.madock/projects/{project_name}/config.xml .madock/config.xml- Edit
.madock/config.xmlmanually as needed.
Important:
.madock/config.xmlis read-only for madock — CLI commands (service:enable/disable,config:set,debug:enable/disable,cron:enable/disable) always write to~/.madock/projects/{project_name}/config.xml. This allows.madock/config.xmlto be safely committed to your repository without unexpected modifications on servers or CI environments.
Everything under the project's .madock/ is committed, so every developer and
every server on the project reads the same files: config.xml and every
template under .madock/docker/. What config:set writes —
~/.madock/projects/<project>/ — is each machine's own.
The people sharing those files do not all run the same madock. A newer madock keeps reading names that were renamed, so an older file is never the problem. A newer one is: a setting, a template function or a snippet that an older madock does not know. A missing snippet or function stops the render with an error; an unknown setting would render as empty, so madock names it on every render of a project's own template:
.madock/docker/docker-compose.yml reads settings this madock does not have, so they render empty:
nginx/port/project
When a project starts relying on something new, say which madock it needs, in
.madock/config.xml:
<config>
<scopes>
<default>
<madock>
<min_version>4.4.0</min_version>
</madock>
</default>
</scopes>
</config>An older madock then refuses every project command and names the version to
update to; madock version and the other global commands still run. madock
never writes this key and never creates the file for it — it is the project's
statement. madock-pro reads madock_pro/min_version the same way.
Support for old names and old syntax lasts until the next major release and is
removed in it; src/helper/deprecation/deprecation.go lists what is kept and
the release that removes it.
- Version Control: Track configuration changes in Git without risk of automatic overwrites
- Team Sharing: Share consistent environment settings with team members
- Portability: Move project with all settings intact
- Server Safety: CLI commands won't modify committed config files
List all project settings:
madock config:listSet a configuration value:
madock config:set --name=php/version --value=8.2When a change takes effect. The compose files and Dockerfiles are rendered
from the config on every start, restart and rebuild. If the render differs
from what the running containers were created from, start says so and brings
them in line — docker compose start only wakes existing containers and would
otherwise keep running the old definition. A change that no template reads (an
SSH host, a cron flag) renders identically and starts the containers as they are.
How much is touched depends on what changed. start knows what each
container was created from, per service, and does the least that applies:
| What changed | What happens |
|---|---|
a file nginx mounts — the vhost, a vhost.d/ snippet |
nginx -t, then nginx -s reload; no container restarts |
a file another service mounts — my.cnf, a php ini |
that service is restarted |
| a service's own definition — its Dockerfile, image, environment, ports | that service is recreated (and its image rebuilt); nginx reloads so it resolves the new address |
| a service added | it is created |
| a service removed, a network or named volume, anything outside one service | the whole stack is recreated, as before |
A vhost edit therefore no longer costs a database restart. Measured on a live
store before this existed: a release whose only change was the nginx vhost
recreated every container — MariaDB and OpenSearch restarted, five
Connection refused in the application log, a 500 to a visitor.
madock rebuild still recreates everything; that is what it is for. madock rebuild --changed applies the table above and leaves every other container
running, and falls back to the full rebuild when the change is not one
service's own. It is what a deploy runs.
Derived options cannot be set: nodejs/major_version is computed from
nodejs/version on every read, so config:set refuses it and names the option to
set instead.
Remove a configuration value, so whatever is underneath it applies again:
madock config:unset --name=php/version
madock config:unset -n a -n b --global--global also removes the value from the installation-wide settings, the ones
config:set --global writes and every project of the installation reads.
Why this exists. madock keeps two copies of a project's configuration: the
one in the project ({project}/.madock/config.xml, committed to your
repository) and a machine-side one under ~/.madock/projects/{name}/, seeded
from it the first time the project is seen. Reads merge both, and the project's
copy wins — so adding or changing a setting in git reaches every machine.
Deleting one did not. The machine-side copy kept it, config:set can only
assign, and clearing the cache does not touch the file, so the only way to drop
a single key was to remove the project and set it up again. A team that retires
a setting, commits and rolls out otherwise leaves every machine living by the
old value, with nothing failing and nobody told.
config:unset reads the value back afterwards rather than trusting the write:
if the key is still set — because the project's own config also sets it, and
that file wins — it says so and where to look, instead of reporting a removal
that did not happen.
Clear configuration cache:
madock config:cache:cleanSettings are inherited in this order (later overrides earlier):
~/.madock/config.xml(global defaults)~/.madock/projects/config.xml(global project defaults)~/.madock/projects/{project_name}/config.xml(project settings){project_root}/.madock/config.xml(local project settings)
One setting is deliberately outside that chain, and outside <scopes>:
<?xml version="1.0" encoding="UTF-8"?>
<config>
<allow_destructive_commands>true</allow_destructive_commands>
<scopes>
...
</scopes>
</config>allow_destructive_commands decides whether the commands that destroy a
project's data may run on this machine:
project:remove— the registry entry, the generated runtime, the ports, the volumes, the images, and a recursive delete of the project directory.project:remove --registry-onlyis covered too, with one exception: an entry that is not a project of its own — its source directory gone, its link resolving to nothing, or its path inside another registered project — may be removed while the setting isfalse. Such an entry owns nothing that could be lost, and refusing kept three of them on a production host with no way to clean up. Containers of that name go; volumes and images are left, so the exemption cannot destroy data even if the entry turns out to have some.prune --with-volumes—docker compose down -v --rmi all: the data volumes and the images. The database is gone and nothing brings it back.
Set it to false and both refuse, naming the file to edit.
Plain prune is not covered, deliberately. It is docker compose down:
containers and the network go, the volumes and images stay, the project
directory and its registry entry are untouched, and madock start puts it back.
Guarding it would obstruct without protecting — and inconsistently, since stop
takes the same site down with nothing in front of it.
It sits at the top level because everything under <scopes> is reachable from a
project: the project's own .madock/config.xml overrides it and config:set
writes it. A guard a project can switch off is not a guard, so this one is
readable only from ~/.madock/config.xml — the file belonging to whoever
administers the installation. A copy of the key inside a project's config, or
inside <scopes>, is ignored.
It is a guard rail, not a security control. The file sits beside the binary and is writable by the same user, so anyone who can run the command can also edit the file first. It stops a mistake, not a person.
The default is true: on a laptop, projects are created and removed all day, and
a guard that gets in the way there is a guard people learn to switch off.
madock-pro ships it as false, because that edition is the one that runs on
servers — and the file still has the last word there, so a machine that needs it
does not need a different binary.
| Key | Description | Default |
|---|---|---|
platform |
Project platform (magento2, shopware, prestashop, shopify, custom) |
magento2 |
nginx/enabled |
Give the project a web server — see below | true |
language |
Programming language for custom platform (php, nodejs, python, golang, ruby, none) |
php |
timezone |
Container timezone | UTC |
php/enabled |
Enable PHP container | false (set true by setup for PHP-based platforms) |
php/version |
PHP version | 8.2 |
nodejs/enabled |
Standalone Node.js container | false |
nodejs/embedded/enabled |
Node.js inside the application container — see below | false |
nodejs/env |
NODE_ENV inside the container |
development |
nodejs/script |
What the container runs — see below | (empty: pick from package.json) |
nodejs/script_type |
How to read nodejs/script: auto, package, command |
auto |
nodejs/browser_libs |
Install the shared libraries a headless browser needs, in the standalone Node.js container | false |
nodejs/embedded/browser_libs |
The same for the application container, whatever its language (needs nodejs/embedded/enabled) |
false |
php/browser_libs |
Old name of nodejs/embedded/browser_libs, still read |
false |
python/version |
Python version (custom platform) | 3.12 |
go/version |
Go version (custom platform) | 1.22 |
ruby/version |
Ruby version (custom platform) | 3.3 |
These used to be literals inside templates; they are settings now, and each
default is the value that was compiled in, so a project that sets nothing gets
what it had. Set a project's value with config:set and apply it with
madock rebuild --changed, which touches only the services the change belongs
to — a vhost change is an nginx -s reload, a php change recreates php alone:
madock config:set --name=php/ini/memory_limit --value=2G
madock config:set --name=php/ini/upload_max_filesize --value=200M
madock config:set --name=nginx/max_body_size --value=200M
madock rebuild --changedconfig:set writes ~/.madock/projects/<project>/config.xml. A key that the
project's own .madock/config.xml sets wins over it — edit it there instead.
| Key | Default | What it is | Applied by |
|---|---|---|---|
php/ini/memory_limit |
756M |
memory_limit of web requests, passed by the vhost |
nginx reload |
php/ini/max_execution_time |
18000 |
max_execution_time of web requests, passed by the vhost — every location, Magento's /setup included — and how long nginx waits for php-fpm (fastcgi_read_timeout) |
nginx reload |
php/ini/post_max_size |
80M |
php.ini |
php rebuild |
php/ini/upload_max_filesize |
50M |
php.ini |
php rebuild |
php/ini/max_input_vars |
50000 |
php.ini |
php rebuild |
php/ini/session_cookie_lifetime |
2592000 |
php.ini |
php rebuild |
php/ini/session_gc_maxlifetime |
1440 |
seconds a session file may sit unused before Debian's sessionclean cron deletes it; written into the fpm and the cli php.ini. Raise it when an application keeps its sessions in PHP's own files and people are logged out early. sessionclean works in whole minutes (value / 60, rounded down), so anything under 60 deletes every session file at each run |
php rebuild |
php/fpm/max_children |
40 |
the most workers php-fpm starts | php rebuild |
php/fpm/start_servers |
2 |
workers started at boot | php rebuild |
php/fpm/min_spare_servers |
1 |
idle workers kept at least | php rebuild |
php/fpm/max_spare_servers |
3 |
idle workers kept at most | php rebuild |
Every key under php/ini/ is the php.ini directive of the same name; what
differs is how it gets there, and that is the last column. memory_limit and
max_execution_time are handed to php-fpm by the vhost with every request as
PHP_VALUE, so they apply to web requests only — never to the CLI, cron or
queue consumers — and an nginx reload applies them. The rest are written into
php-fpm's php.ini when the image is built — the CLI keeps its own php.ini
and is not changed — so they need a php rebuild, and an edit to php.ini inside
a running container does not survive the next one.
Until 4.3.1 the first two were php/limits/memory and
php/limits/max_execution_time; those names are still read until 5.0.0. Magento's
/setup had a time limit of its own, php/limits/max_execution_time_web (600);
it now reads php/ini/max_execution_time like every other location. A copied
template that still asks for the old key gets max_execution_time; a value
stored under the old key is not read, because it was meant for /setup alone
and would otherwise become the limit of every request.
Every idle worker
holds memory of its own, which is why the spare values are small: a burst
spawns up to max_children as it arrives.
A web request has three time limits, and the smallest one wins: php's
max_execution_time, the project's nginx waiting for php-fpm, and the shared
proxy waiting for the project (proxy/timeout/read, 300 seconds by default,
below). The first two are one setting — nginx waits exactly as long as php may
run, and 0 (no limit in php) waits a day. The proxy is the machine's: a
project that needs requests longer than five minutes raises it with --global
as well, and that applies to every project on the machine.
An upload has to pass three limits, and the smallest one wins:
php/ini/upload_max_filesize (and post_max_size), the project's
nginx/max_body_size (default 2G), and the shared proxy's
proxy/max_body_size (default 128M, below).
| Key | Default | What it is | Applied by |
|---|---|---|---|
db/memory |
768M |
the database's budget, divided between its buffers in my.cnf |
db restart |
db/flush_log_at_trx_commit |
0 |
innodb_flush_log_at_trx_commit in my.cnf, MySQL and MariaDB. 0 writes the redo log about once a second, so a crash of the machine loses up to a second of acknowledged commits; 1 makes each commit durable before it returns; 2 survives the database crashing but not the machine. madock Pro defaults to 1 |
db restart |
search/opensearch/heap |
1g |
the JVM heap | search recreate |
search/opensearch/memory_limit |
2512m |
the container's limit | search recreate |
search/elasticsearch/heap |
800m |
the JVM heap | search recreate |
search/elasticsearch/memory_limit |
2512m |
the container's limit | search recreate |
memcached/memory |
256 |
megabytes | memcached recreate |
varnish/size |
1G |
the cache storage, VARNISH_SIZE — filled as pages are cached, not reserved at start |
varnish recreate |
shopware/messenger/memory_limit |
512M |
messenger:consume --memory-limit: the worker exits past it and is restarted |
messenger recreate |
shopware/messenger/time_limit |
3600 |
messenger:consume --time-limit, seconds |
messenger recreate |
sylius/messenger/memory_limit |
256M |
as above | messenger recreate |
sylius/messenger/time_limit |
3600 |
as above | messenger recreate |
The search engine needs memory beyond its heap, so the limit has to be well above it; a heap that does not fit under its limit is refused when the configuration is rendered, rather than killed later.
There is one proxy per machine, so its settings belong to the installation, not
to a project: set them with --global, and apply them with madock proxy:start,
which regenerates the proxy configuration and reloads it when it changed.
madock config:set --global --name=proxy/max_body_size --value=512M
madock config:set --global --name=proxy/ssl/protocols --value="TLSv1.3"
madock proxy:start| Key | Default | What it is |
|---|---|---|
proxy/max_body_size |
128M |
the largest request body the proxy accepts |
proxy/ssl/protocols |
TLSv1.2 TLSv1.3 |
ssl_protocols |
proxy/ssl/ciphers |
a modern ECDHE/CHACHA20 list | ssl_ciphers, colon-separated |
proxy/worker/processes |
2 |
worker_processes |
proxy/worker/connections |
4096 |
worker_connections |
proxy/worker/rlimit_nofile |
200000 |
worker_rlimit_nofile |
proxy/server_names_hash/bucket_size |
128 |
raise it when nginx refuses a long host name |
proxy/server_names_hash/max_size |
1024 |
raise it with many host names on one machine |
proxy/timeout/connect |
60 |
proxy_connect_timeout, seconds |
proxy/timeout/send |
300 |
proxy_send_timeout, seconds |
proxy/timeout/read |
300 |
proxy_read_timeout, seconds: the longest a request through the proxy waits for an answer, whatever the project allows behind it |
Without --global, a proxy/ key is written into the project and changes
nothing — the proxy reads the installation's config only. A value nginx cannot
read stops the proxy, and the proxy serves every project on the machine; check
madock proxy:logs after a change.
| Key | Default | What it is |
|---|---|---|
snapshot/engine |
tar |
what snapshot:create, snapshot:restore and project:clone copy the databases (dbdata, dbdata2) with. tar stops the project and archives the data directory. Any other value is an engine a build registers — madock Pro adds them; a value this build does not have is refused, not copied with tar |
snapshot/live |
auto |
auto: an engine whose snapshot is atomic keeps the project running; stop: the project is stopped for every snapshot. A project with named volumes the engine leaves to tar (search index, Grafana, persisted Redis/RabbitMQ) is stopped either way |
snapshot/keep |
0 |
how many snapshots the project holds; after each snapshot:create the oldest are removed beyond it. 0 is no limit. A snapshot its engine will not drop (a clone lives on it) is kept |
clone/muted |
false |
true on a copy that must not act as its source: cron off (and cron:enable refused), mail() to mailpit. project:clone --muted sets it |
ports/publish |
true |
false publishes no port of the project on the host; the shared proxy reaches its nginx (or varnish) over madock-proxy by container name. A varnish VCL pointing at host.docker.internal:<port> stops working then — point it at nginx:80 |
redis/persist, valkey/persist, rabbitmq/persist |
false |
true gives the service a named volume, so its data survives a recreated container and is carried by snapshots and clones. RabbitMQ also gets a fixed hostname |
Project files are archived with tar whatever the engine. A snapshot taken by
an engine holds engine.json in place of db.tar.gz, and snapshot:restore
hands it back to that engine — the one the snapshot names, not the one the
project is set to now — so snapshots taken before the key changed restore as
they always did.
madock config:set --name=nodejs/enabled --value=true # a container of its own
madock config:set --name=nodejs/embedded/enabled --value=true # inside the app container
madock service:enable nodejs/embedded # the same thing, shorternodejs/enabledgives the project a Node container running its own process — a Node backend, a dev server, a worker.nodejs/embedded/enabledputs the Node binaries inside the application container, next to whatever language it runs. That is what a build step needs: grunt, webpack, vite, anpm run buildduring deployment.
Both can be true at once, and neither implies the other.
Until 3.9.8 the second was spelled php/nodejs/enabled, which said node was
PHP's business. It is not: a Python service with a JavaScript front end, or a Go
one with an admin panel, needs exactly the same thing, and the version was
already shared at nodejs/version. The rename carries itself — a migration
moves the key in the installation config, in every project's registry config, in
each project's own .madock/config.xml, and in any template a project copied
under .madock/docker/.
php/yarn/enabled went the same way, to nodejs/yarn/enabled. That one was
never declared at all: no default carried it, three platform configurators set
it, and one template read it — while a real nodejs/yarn/enabled sat unused in
the defaults.
Which images offer it: all of them — php, python, ruby and golang. Every one of those base images is Debian or Ubuntu, so the same nodesource install works in each.
The old names still work. madock service:enable php/nodejs is accepted,
resolves to nodejs/embedded, and prints the new name once so it is learned
from the command rather than from a changelog. php/yarn is aliased the same
way, though it was never a registered service — it worked only on the three
platforms whose configurator happened to write php/yarn/enabled. Both are
aliases rather than a second spelling, and both will be removed once the new
names are the ones in people's fingers.
With nginx/ssl/enabled (the default) madock creates its own CA, CN=madock,
and trusts it in the host's store, so the browser opens https://<project>.test.
Since 4.5.19 every application image (php, app, golang, python, ruby, nodejs)
trusts it too: the CA is installed into /usr/local/share/ca-certificates/ and
update-ca-certificates puts it in the bundle and as a hash file, so PHP's
file_get_contents, curl, Python's requests and Node reach
https://<project>.test from inside a container without verify_peer=false or
SSL_CERT_FILE. Before, it worked only on OrbStack, and only for tools that read
the bundle, because OrbStack copies the host's roots in.
The CA is part of the image, so it changes only with a rebuild. madock renews it
after a year and says so; then run madock rebuild in each project:
madock rebuild
madock cli php -r 'var_dump(file_get_contents("https://<project>.test/robots.txt") !== false);'Some projects answer no request and never will: a queue worker, a bus consumer,
the service that owns a shared database schema while its neighbours take their
own webhooks. nginx/enabled=false leaves the web server out completely — no
container, no vhost, no block in the shared proxy, no name in the shared
certificate, and no ports reserved.
madock config:set --name=nginx/enabled --value=false
madock rebuildRemoving the project's <hosts> does not do this, which is the trap worth
knowing about: the container still starts, and a project with no hosts gets
loc.<project>.com invented for it, so its block in the shared proxy is renamed
rather than removed and the two ports stay reserved.
To check:
madock status # no nginx line
madock info:ports # no port for nginx
grep -c "<project-host>" <MADOCK_ROOT>/aruntime/ctx/proxy.conf # 0Varnish sits in front of nginx, so it has nothing to do on a project without
one — the depends_on is dropped so compose still reads the file, but enabling
both is a configuration nobody needs.
Left alone, the container picks a script out of package.json: dev when
nodejs/env is development, start when it is production.
That default is why nodejs/env stopped being hardcoded. For a Shopify app,
dev is shopify app dev — an interactive command that prints a verification
code and waits for someone to log in. On a server nobody does, it gives up, and
the container dies with it, because that command is its main process. start
reported success minutes earlier.
nodejs/script says what to run instead, and nodejs/script_type says how to
read it:
script_type |
Meaning |
|---|---|
auto (default) |
A name package.json declares is run as a script; anything else is run as a command, and madock says which it chose |
package |
Always a package.json script. A name it does not declare stops the container with an explanation instead of failing at exec |
command |
Always a shell command |
madock config:set --name=nodejs/script --value=docker-start
madock config:set --name=nodejs/script --value="node server.js --port 3000"
madock config:set --name=nodejs/script_type --value=commandA script goes through the package manager the project actually uses — yarn, pnpm or npm, detected from the lockfile. A path to a file is a command.
nodejs/browser_libs (and nodejs/embedded/browser_libs for an application
container with Node inside, PHP, Go, Python or Ruby) installs the shared
libraries a headless Chromium needs. Off by default: most projects have no
browser, and the libraries are weight and surface they do not need.
php/browser_libs is the old name of nodejs/embedded/browser_libs and is still
read, so a project that sets it changes nothing.
The list is not written down anywhere in madock — the image asks Playwright for
it at build time (playwright install-deps), because the package names differ
per distribution and move between releases: libasound2 became libasound2t64
in Debian trixie and Ubuntu 24.04, so a list pinned by hand breaks the build the
day the base image is bumped.
Installing them from inside a running container does not work and is not worth
attempting: madock execs as a non-root user, so Playwright shells out to sudo
and stops at a password prompt — and anything apt installs into a running
container is gone at the next rebuild.
See also: Scopes for managing multiple environments per project.