# Installation and First Deploy

This guide takes you from zero to your first container running in production in five minutes.

# Prerequisites

• Linux server (x86_64 or aarch64) with Docker 20.10+ installed
• sudo access on the server
• Traefik container already running (or deploy the traefik template first)
• A domain pointing to the server's IP (so TLS can be issued automatically)

# 1. Install the CLI

The installer detects the architecture automatically and drops the binary in /opt/deployally/ with a symlink in /usr/local/bin/:

curl -fsSL https://get.deployally.com/init.sh | sudo bash

To use the release candidate channel:

curl -fsSL https://get.deployally.com/init.sh | sudo bash -s -- --rc

# Verify the install

deployally --version

Expected output (exact version reflects the current release):

deployally <version>

# 2. Inspect the Catalog

To see what's available, validate any catalog template. For example, memos:

deployally validate --species memos

The output lists every section declared in the template (required inputs, secrets that will be generated, HTTP routes, healthcheck) and ends with valid when everything is consistent.

# 3. First Deploy

Let's ship Memos — a personal notes service. It's a simple application template with no external dependencies.

deployally deploy \
  --species memos \
  --instance-uid memos-001 \
  --input WEB_HOSTNAME=memos.example.com \
  --apply

Replace memos.example.com with a real domain pointing to the server.

# What happens

1. The CLI fetches the memos template from the registry (or uses the local cache).
2. It runs the wizard for any missing inputs — in this case none, since we passed WEB_HOSTNAME via flag.
3. It generates secrets automatically as declared by the template (hex tokens, passwords).
4. It runs a DNS preflight for memos.example.com.
5. It starts the container with Traefik labels for HTTPS routing.
6. It waits for the healthcheck to report healthy.

# Verify the deploy

docker ps --filter "label=ccs.systems/uid=memos-001"
curl -I https://memos.example.com

The second command should return HTTP/2 200 (after Traefik issues the Let's Encrypt certificate, which can take a few seconds on the first request).

# 4. Deploy with Auto-Provisioning

Applications like WordPress need a database. DeployAlly provisions missing assets automatically:

deployally deploy \
  --species wordpress \
  --instance-uid blog-001 \
  --input WEB_HOSTNAME=blog.example.com \
  --input ADMIN_EMAIL=admin@example.com \
  --provision-missing-assets \
  --apply

If no MySQL is running, the deployer:

1. Detects the dependency (needs.options[0] declared in the WordPress template).
2. Spins up MySQL automatically using the first default variant.
3. Waits for the asset to become healthy (retry with exponential backoff).
4. Starts WordPress connected to the freshly provisioned MySQL.

# 5. Profiles

Profiles tune resources per environment (memory, CPU, pool size):

# Deploy with production profile (more resources)
deployally deploy --species memos \
  --instance-uid memos-prod \
  --input WEB_HOSTNAME=memos.example.com \
  --profile production \
  --apply

Available profiles vary by template. Check the output of deployally validate --species <X> for the options.

# 6. Dry-Run

To see what would happen without applying anything:

deployally deploy --species memos \
  --instance-uid memos-001 \
  --input WEB_HOSTNAME=memos.example.com \
  --dry-run

The output shows the containers that would be created, the secrets that would be generated, the networks, and the Traefik labels — without executing anything.

# 7. Update the CLI

deployally self-update          # stable channel
deployally self-update --rc     # release candidate

The command downloads the new version from the CDN, validates it (-V), replaces the binary, and restores the backup automatically if anything fails.

# 8. File Layout

After the first deploy, DeployAlly keeps state in:

/opt/deployally/
├── deployally               # binary
├── config.yaml              # global config (if any)
└── manifests/               # per-instance manifests
    └── <instance-uid>/
        ├── manifest.yaml    # rendered spec
        ├── secrets.json     # generated secrets (chmod 600)
        └── config/          # config_file artifacts mounted into containers

# Next Steps

• Reflang Reference — write or customize templates
• CLI Reference — every command and flag
• Templates — how archetypes work
• Service Ecology — how dependencies are resolved

# Common Issues

# "no running asset matched class X"

The application declares a dependency (needs) on an asset that isn't running. Options:

# Bring the asset up manually
deployally deploy --species mysql --instance-uid mysql-shared --apply

# Or use auto-provisioning
deployally deploy --species wordpress --instance-uid blog-001 \
  --provision-missing-assets --apply

# "DNS preflight failed"

The domain doesn't resolve to the server. Check the A/AAAA record before deploying:

dig +short memos.example.com

# "Docker not found"

Install Docker first:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

For more errors, see Troubleshooting.