Skip to content

Latest commit

 

History

History
530 lines (429 loc) · 27.2 KB

config.md

File metadata and controls

530 lines (429 loc) · 27.2 KB

Project Configuration

Madock configuration can be stored either globally or within a project folder.

Configuration Locations

Global configuration (default)

~/.madock/
├── config.xml                    # Global settings
└── projects/
    └── {project_name}/
        ├── config.xml            # Project-specific settings
        └── backup/
            └── db/               # Database backups

Project-local configuration

{project_root}/
└── .madock/
    ├── config.xml                # Project settings (version controlled)
    ├── backup/
    │   └── db/                   # Database backups
    └── docker/                   # Custom Docker overrides

Setting Up Project-Local Configuration

  1. Create the .madock folder in your project root:
mkdir -p .madock
  1. Create or copy config.xml with the settings you want:
cp ~/.madock/projects/{project_name}/config.xml .madock/config.xml
  1. Edit .madock/config.xml manually as needed.

Important: .madock/config.xml is 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.xml to be safely committed to your repository without unexpected modifications on servers or CI environments.

What is shared by a team, and which madock it needs

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.

Benefits of Project-Local Configuration

  • 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

Configuration Commands

List all project settings:

madock config:list

Set a configuration value:

madock config:set --name=php/version --value=8.2

When 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:clean

Configuration Inheritance

Settings are inherited in this order (later overrides earlier):

  1. ~/.madock/config.xml (global defaults)
  2. ~/.madock/projects/config.xml (global project defaults)
  3. ~/.madock/projects/{project_name}/config.xml (project settings)
  4. {project_root}/.madock/config.xml (local project settings)

Settings that belong to the installation, not the project

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-only is 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 is false. 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 Configuration Options

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

Limits, php.ini, memory and the proxy

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 --changed

config: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.

PHP

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).

Memory of the services

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.

The shared proxy

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.

Snapshots

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.

Node.js in two places, and they are different questions

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, shorter
  • nodejs/enabled gives the project a Node container running its own process — a Node backend, a dev server, a worker.
  • nodejs/embedded/enabled puts the Node binaries inside the application container, next to whatever language it runs. That is what a build step needs: grunt, webpack, vite, a npm run build during 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.

HTTPS to a project from inside a container

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);'

A project with no web server

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 rebuild

Removing 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   # 0

Varnish 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.

What the Node container runs

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=command

A 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.

Headless browsers

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.