Declarative Stacks

Managing servers imperatively (e.g., typing super start commands manually) works for small setups, but it leads to Configuration Drift at scale. You forget which arguments you used last week, or someone else changes a setting without documenting it.

Super supports a Declarative approach, similar to kubectl apply or docker-compose up. You define the desired state of the entire system, and Super converges to that state.

The Concept: “Apply”

Instead of managing individual processes, you define a Stack (a list of all services) in a JSON file.

When you run super apply stack.json, Super will:

1. Create new services that are in the JSON but not in the system.
2. Update existing services if their configuration (args, env, etc.) has changed.
3. Prune (Remove) services that are running in the system but missing from the JSON (if prune: true).

Workflow Example

1. Define the Stack

Create a file named prod-stack.json. This can be generated by your CI/CD system or managed in Git.

{
  "prune": false,
  "services": [
    {
      "name": "redis-cache",
      "command": "/usr/bin/redis-server",
      "autostart": true
    },
    {
      "name": "backend-api",
      "command": "/usr/local/bin/api",
      "env": { "PORT": "8080" },
      "depends_on": ["redis-cache"],
      "health_check": {
        "type": "tcp",
        "port": 8080
      }
    }
  ]
}

2. Apply the Stack

Run the apply command via the CLI.

$ super apply prod-stack.json

Applying stack from "prod-stack.json"...
- Creating service: redis-cache
- Updating service: backend-api
- Pruning service: old-worker (not in stack)
Stack applied successfully.

CI/CD Integration

This feature makes Super ideal for GitOps.

1. Commit your stack.json to a Git repository.
2. Configure a GitHub Action / GitLab Runner.
3. On push to main, the runner executes:

   curl -X PUT http://prod-server:9002/api/v1/stack \
     -H "Authorization: Bearer $TOKEN" \
     -d @stack.json

Exporting Current State

If you have manually configured a server and want to capture its state into a file, you can use the export command:

$ super export > current-stack.json

This generates a valid JSON stack file representing the currently running system, which you can then check into version control.