stackconfdump

pip install stackconfdump

Read a Dokploy database dump and write the shape of one project as a portable JSON or YAML file, without runtime data and without secrets.

Why

Dokploy can move services from one server to another, but there is no text file that describes a project: no file to read, to put under version control, or to hand to someone else. The request for one is Dokploy/dokploy#1733, where the use case is written as spinning up a mirror of a production project on a second server without re-creating every application by hand.

This tool does the reading half. It does not write anything back into an instance.

Use

stackconfdump backup.sql --list
stackconfdump backup.sql --project shop > shop.json
stackconfdump backup.sql --project shop --format yaml --output shop.yaml

The input is the plain text dump that pg_dump produces for the Dokploy database, plain or gzipped. Nothing is read from a running instance, no connection is opened, and the dump is never modified.

Options:

• --list print the project names held by the dump and exit.
• --project NAME which project to export, required when the dump holds more than one.
• --format json|yaml output format, json by default.
• --output FILE write to a file instead of standard output.
• --strict also drop the free text fields a person types by hand.
• --include-compose-file include the raw compose file of each compose service.

What comes out

For the chosen project: its environments, and inside each one the applications, the compose services and the databases. An application carries its name, its source (git repository, owner, branch, build path, or the docker image), its build type, its replicas and resource limits, its domains, its published ports, its redirects, its mounts, and the number of basic auth users. A database carries its engine, its image, its database name and user, its external port and its mounts. Every environment block is reduced to the list of its key names.

{
  "format": "stackconfdump/1",
  "secretsOmitted": true,
  "project": {
    "name": "shop",
    "environments": [
      {
        "name": "production",
        "envKeys": ["STAGE", "API_KEY"],
        "applications": [
          {
            "name": "storefront",
            "sourceType": "github",
            "repository": "storefront",
            "branch": "main",
            "buildType": "nixpacks",
            "replicas": 2,
            "envKeys": ["DATABASE_URL", "STRIPE_KEY"],
            "domains": [
              {
                "host": "shop.example.com",
                "https": true,
                "port": 3000
              }
            ]
          }
        ]
      }
    ]
  }
}

How secrets are kept out

The rule is an allow list, not a filter on suspicious names. A column reaches the output only when this tool names it. Anything else, including a column added to Dokploy after this release, is absent until someone adds it on purpose. That is the direction in which this should fail.

Named and never exported: every password and root password, registry credentials, refresh tokens, basic auth users and passwords, and the body of a file mount. Environment blocks, preview environment blocks and build arguments are reduced to their key names, so API_KEY is reported and its value is not. The compose file of a compose service is left out by default, because inline environment values inside it are secrets; --include-compose-file puts it back and you should read the result before sharing it.

The custom git URL and the registry URL are exported with their user info part removed, so https://oauth2:TOKEN@git.example.com/acme/app.git comes out as https://git.example.com/acme/app.git. That is a removal by position, not a guess on what looks like a secret: everything between the scheme separator and the last at sign of the authority goes, whatever it held.

Two holes are left open on purpose, and they are named here rather than papered over:

1. Free text. description and the start command are copied as they were written. Someone who pasted a token into a start command will find it in the output. --strict drops both.
2. Advanced swarm settings. Placement, labels, health check and update config are stored as serialized blobs. They are not exported at all, so a project that relies on them will not be fully described by the output.

Run the tool and read the file before you hand it to anyone. This tool reduces what leaves the dump; it does not certify the result.

What is not verified

No real instance was read. The schema comes from the public Dokploy repository, and the tests run against an example dump written for the tests. If you run this against a real backup and it reads something wrong, or lets something through that it should not, please open an issue with the column name and it will be fixed.

The tool understands the COPY form of pg_dump. A dump made with --inserts is refused with a message saying so.

Install from source

git clone https://github.com/Rezarys/stackconfdump
cd stackconfdump
pip install -e ".[dev]"
python -m pytest

Notes

Built with AI assistance, reviewed and tested by me. MIT licensed. Not affiliated with Dokploy.

Younes Z.