Concepts

Tarsail is small, but it has a few concepts that are important to understand before using it for serious deployments.

Project

A Tarsail project is the local directory that contains:

• tarsail.yml;
• the Docker Compose file referenced by compose.file;
• Dockerfiles and source code used by the Compose build;
• optional release files referenced by files;
• optional local env and secret files referenced by compose.env_file and secrets.

The config file location defines the project root. Relative paths in tarsail.yml are resolved from that root.

Target

A target is the remote Linux server configured under target.

Phase 0 supports exactly one target per config file:

target:
  name: prod
  host: example.com
  user: deploy
  port: 22
  path: /opt/my-app

The target path must be project-specific. Tarsail rejects broad paths such as /, /opt, /var, /home, /root, /tmp, /etc, or /usr.

Release ID

Each deployment creates a release ID such as:

20260622-101530-a1b2

The release ID is used in:

• bundle file names;
• release directories;
• manifest.json;
• the generated .tarsail.env;
• image tags when Compose uses ${TARSAIL_RELEASE_ID:-local}.

Release bundle

A release bundle is a gzip-compressed tar archive created locally.

It contains:

manifest.json
compose.yaml
images/
  web.tar
  worker.tar
files/
  ...

It does not contain:

• SSH private keys;
• SSH passwords;
• configured compose.env_file contents;
• configured secrets contents;
• Docker volumes;
• database dumps;
• files outside the configured release file list.

Manifest

manifest.json records release metadata:

{
  "schema_version": 1,
  "project": "my-app",
  "release_id": "20260622-101530-a1b2",
  "created_at": "2026-06-22T10:15:30Z",
  "created_by": "tarsail",
  "compose_file": "compose.yaml",
  "images": [
    {
      "service": "web",
      "image": "my-app-web:20260622-101530-a1b2",
      "file": "images/web.tar"
    }
  ]
}

Tarsail uses the manifest for release listing and validation.

Managed files

Managed files are non-secret files or directories copied into the release bundle through the files section:

files:
  - source: deploy/nginx
    target: files/nginx

Use managed files for release-owned assets:

• Nginx config templates;
• static build output;
• local config that is safe to commit;
• scripts used by the Compose services.

Managed files roll back with the release.

Do not put secrets in files.

Shared files

shared/ is a persistent directory under the remote target path.

Use it for runtime files that should remain stable across releases:

• .env files;
• TLS certificates you manage yourself;
• htpasswd files;
• application keys;
• other explicitly configured secret files.

Shared files do not roll back when you run tarsail rollback.

Compose env file

compose.env_file is a special secret file passed to Docker Compose:

compose:
  file: compose.yaml
  env_file:
    source: .deploy/prod.env
    target: shared/.env
    mode: 600

If source is set, Tarsail uploads it during deploy.

If source is omitted, Tarsail expects the target file to already exist on the server:

compose:
  file: compose.yaml
  env_file:
    target: shared/.env

This is useful when secrets are provisioned by another process.

Secrets

The secrets section uploads explicit files to shared/:

secrets:
  - source: .deploy/app.key
    target: shared/secrets/app.key
    mode: 600

Tarsail copies these files and applies the configured mode. It does not encrypt, generate, rotate, validate, back up, or audit secret values.

Activation

After a bundle is uploaded and extracted, Tarsail activates it by updating the remote current symlink:

current -> releases/20260622-101530-a1b2

Then it runs Compose against current/compose.yaml.

If Compose startup fails after activation, Tarsail reports the failure and tells you to run tarsail rollback.

Rollback boundary

Rollback affects:

• current;
• the active compose.yaml;
• bundled images;
• release-owned managed files.

Rollback does not affect:

• databases;
• Docker named volumes;
• bind-mounted directories outside the release;
• shared/ files;
• external services;
• network provider state;
• DNS or certificates.

Treat database migration and data backup as application responsibilities for now.