Metadata-Version: 2.4
Name: stackconfdump
Version: 0.1.0
Summary: Export the shape of one Dokploy project from a database dump as a portable JSON or YAML file, without runtime data and without secrets.
Author: Younes Z.
License: MIT
Project-URL: Homepage, https://github.com/Rezarys/stackconfdump
Project-URL: Issues, https://github.com/Rezarys/stackconfdump/issues
Keywords: dokploy,self hosted,paas,docker,export,configuration,infrastructure as code,migration,postgres,pg_dump
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pyyaml>=6; extra == "dev"
Dynamic: license-file

# 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](https://github.com/Dokploy/dokploy/issues/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.

```json
{
  "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.
