Secrets and env files

Tarsail transfers secrets only when you explicitly configure them.

It is not a secrets manager. It does not generate, encrypt, rotate, back up, validate, or audit secret values. It copies configured files over SSH and applies the configured file mode.

The two secret paths

Tarsail has two related config areas:

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

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

compose.env_file is passed to Docker Compose with --env-file.

secrets are uploaded files that your Compose services may mount or read, but Tarsail does not automatically pass them to Compose.

Env file upload

Use compose.env_file.source when the deployment machine has the runtime env file:

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

During deploy, Tarsail uploads .deploy/production.env to:

<target.path>/shared/.env

Remote Compose receives:

--env-file shared/.env

Pre-provisioned env file

If another process creates the env file on the server, omit source:

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

In this mode:

• doctor checks that shared/.env exists;
• deploy does not upload a local env file;
• Compose still receives --env-file shared/.env.

Secret files

Use secrets for files that should exist under shared/:

secrets:
  - source: .deploy/htpasswd
    target: shared/auth/htpasswd
    mode: 600
  - source: .deploy/tls/fullchain.pem
    target: shared/tls/fullchain.pem
    mode: 644
  - source: .deploy/tls/privkey.pem
    target: shared/tls/privkey.pem
    mode: 600

Targets must be under shared/.

Mounting uploaded secrets

A Compose service can mount shared files:

services:
  reverse-proxy:
    image: nginx:1.27-alpine
    volumes:
      - ./shared/tls/fullchain.pem:/etc/nginx/tls/fullchain.pem:ro
      - ./shared/tls/privkey.pem:/etc/nginx/tls/privkey.pem:ro
      - ./current/files/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro

Tarsail runs Compose from <target.path>, so ./shared/... points to the remote shared directory and ./current/... points to the active release.

File modes

Default mode:

mode: 600

Accepted format:

600
0644

Use 600 for private secrets. Use 644 only for files that are safe for normal read access, such as a public certificate.

Local file safety

Keep real files in an ignored directory:

.deploy/
  production.env
  app.key
  tls/
    fullchain.pem
    privkey.pem

Example .gitignore:

.deploy/*
!.deploy/.gitignore
!.deploy/README.md

Commit placeholders instead:

.env.example
.deploy/README.md

What Tarsail redacts

Tarsail redacts common sensitive output patterns in command output and errors. This helps reduce accidental leaks in logs, but it is not a substitute for careful secret handling.

Do not rely on redaction as a security boundary.

What Tarsail never does

Tarsail does not:

• print env file contents;
• include configured env files in release bundles;
• include configured secret files in release bundles;
• store SSH passwords;
• upload SSH private keys;
• discover .env files automatically;
• search the project for secrets;
• rotate leaked credentials;
• encrypt shared/;
• back up shared/.

Recommended production practice

For simple projects:

1. keep production env files in .deploy/;
2. add .deploy/* to .gitignore;
3. configure compose.env_file.source;
4. use mode: 600;
5. deploy over SSH key authentication when possible;
6. rotate any secret accidentally committed or pasted into public logs.

For stricter environments, provision shared/.env and secret files outside Tarsail, then configure only target paths. This lets Tarsail verify the files exist without transporting them.