Overview

Tarsail is a release bundler and SSH deployer for Docker Compose projects.

It is designed for teams and individual maintainers who need to deploy Docker Compose applications to servers where pulling images from Docker Hub, GHCR, Quay, or a private registry is unreliable, slow, blocked, or intentionally avoided.

The problem

A normal Docker Compose deployment often assumes the target server can pull all required images:

docker compose pull
docker compose up -d

That assumption fails when:

• the server has restricted outbound network access;
• registry access is slow or unreliable;
• a private registry is not worth operating for a small project;
• deployment must be repeatable even when external registries are unavailable;
• the build machine can reach dependencies, but the server cannot.

Tarsail changes the deployment path. It asks the local machine to do the network-heavy work, then ships a portable release bundle to the server.

Deployment model

Tarsail’s Phase 0 deployment model is deliberately small:

local project
  compose.yaml
  Dockerfile
  .deploy/prod.env

local Docker daemon
  builds images
  saves images as tar files

Tarsail bundle
  manifest.json
  compose.yaml
  images/*.tar
  files/*

SSH target
  /opt/my-app/
    current -> releases/<release-id>
    releases/
    incoming/
    shared/

During deploy, Tarsail:

1. loads tarsail.yml;
2. validates local Docker and Docker Compose;
3. validates the Compose file has explicit image tags;
4. checks SSH, the remote target path, Docker, and Docker Compose;
5. uploads configured env files and secret files into shared/;
6. builds Compose images locally;
7. saves local images into image tar files;
8. creates a .tarsail.tar.gz release bundle;
9. uploads and extracts the bundle on the server;
10. loads images on the server with docker load;
11. points current at the new release;
12. runs docker compose up -d;
13. prints remote Compose status.

Release layout

Tarsail manages a project-specific directory on the server:

/opt/my-app/
  current -> releases/20260622-101530-a1b2
  incoming/
    my-app-20260622-101530-a1b2.tarsail.tar.gz
  releases/
    20260622-101530-a1b2/
      manifest.json
      compose.yaml
      .tarsail.env
      shared -> ../../shared
      images/
        web.tar
        worker.tar
      files/
        nginx/
          default.conf
  shared/
    .env
    secrets/
      app.key

releases/ contains release-owned files and images. shared/ contains runtime files that should survive release changes, such as environment files and uploaded secrets.

Runtime Compose command

On the server, Tarsail runs Compose from the target path and points it at the active release:

docker compose -p my-app \
  --env-file current/.tarsail.env \
  --env-file shared/.env \
  -f current/compose.yaml \
  up -d

The generated current/.tarsail.env file contains TARSAIL_RELEASE_ID. You can use this variable in image tags:

services:
  web:
    build: .
    image: my-app-web:${TARSAIL_RELEASE_ID:-local}

What belongs in each place

Location	Purpose	Rollback behavior
compose.yaml	The release’s Compose definition	Rolls back
images/*.tar	Image tar files created by docker image save	Rolls back
files/	Non-secret release files copied from files:	Rolls back
shared/	Env files and secret files	Does not roll back
Docker volumes	Application runtime data	Does not roll back
External databases	Data outside the release bundle	Does not roll back

When to use Tarsail

Tarsail is a good fit when:

• your application already runs with Docker Compose;
• you deploy to one Linux server;
• the server can accept SSH connections;
• local Docker can build or pull the images;
• the remote server has Docker and Docker Compose v2 installed;
• registry access from the remote server is unreliable or undesired;
• you want a readable release directory and a simple rollback path.

When not to use Tarsail

Tarsail is not the right tool when you need:

• Kubernetes or Docker Swarm orchestration;
• multiple servers in one deployment;
• automatic TLS provisioning;
• automatic database backup or restore;
• container monitoring;
• image registry management;
• blue-green or canary deployment;
• a web dashboard;
• full secret lifecycle management.

Those may be valid needs. They are outside Phase 0.

Maturity

Current maturity: Public Alpha.

Maintenance state: Active.

Phase 0 is intentionally conservative. The supported shape is narrow so behavior can stay understandable:

• one config file;
• one Compose file;
• one target server;
• one active release;
• explicit file transfer;
• explicit environment and secret handling.