Your First Deployment

Goal

Starting from an empty Appaloft instance, complete a minimal deployment: create a project, register a server, create a resource, start a deployment, and get back an access URL you can open in a browser.

When to use this task

You just installed or logged in to Appaloft for the first time and want to verify the whole chain works.
You have an app that already runs locally (a Git repository, a container image, or a built static bundle) and want to deploy it to your own server.

If you just want to understand Appaloft’s core concepts first, read Product Mental Model; if you’re not sure whether to use Web, CLI, or the API, read Choosing an Entrypoint.

Prerequisites

A Linux server you have root or sudo access to, reachable over SSH (Appaloft is BYOS — it does not host servers for you).
A Git repository URL, a container image reference, or an already-built static directory.
You’ve completed Installing Appaloft and Creating The First Admin (self-hosted scenario), or you already have an Appaloft Cloud account.

Inputs and defaults

A minimal deployment needs the following inputs:

Input	Description	Default
Project	The organizing boundary for resources, environments, and deployment history	None — must be explicitly created or selected
Server	The deployment target machine (must be reachable over SSH)	None — must be registered first
Deployment source	A Git repository, container image, or local static directory	None — must be explicitly provided
Runtime profile	Start command, port, health check path	Attempts zero-configuration detection; falls back to explicit input on failure

Zero-configuration auto-detection coverage varies by source type — this page labels it honestly:

Source type	Detection status
Local single-app root directory (CLI pointed straight at a project directory)	Best-verified coverage
Public Git repository with automatic framework detection	Not supported — runtime must be declared explicitly
Native containers (Dockerfile / prebuilt image)	Supported
Remote Git + explicit command profile	Preview — verify locally first
Scoped local-directory discovery inside a monorepo	Preview
Generic workload archive bundle	Not supported

When a monorepo root has multiple candidate apps, the deployment is blocked until you pass baseDirectory explicitly.

Web steps

Sign in to the Web console and create or select a Project.
Go to Servers, click Register server, fill in the host address and SSH credentials, and wait for the connectivity check to pass.
Go to Resources, click Create resource, choose your deployment source (Git repository / container image / uploaded static directory) and the server you just registered.
Confirm the runtime profile (start command, port, health check) and click Deploy.
The deployment panel shows the current lifecycle status; on success it displays an automatically generated access URL.

CLI steps

# 1. Log in (connects to Appaloft Cloud by default; self-hosted requires an explicit --url)
appaloft login --url https://your-appaloft-host

# 2. Create a project (if you don't have one yet)
appaloft projects create --name "my-first-project"

# 3. Register a server and wait for the connectivity check
appaloft server register --host 203.0.113.10 --ssh-user deploy --ssh-key ~/.ssh/id_ed25519
appaloft server capacity inspect --server-id <serverId>

# 4. Start a deployment from the current directory (zero-configuration detection)
appaloft deploy

# 5. Or explicitly point at a config file / profile
appaloft deploy --config appaloft.yml --config-profile staging

# 6. Already have a built static directory? Skip the build step and publish directly
appaloft deploy ./dist --as static-site

# 7. Watch deployment status and timeline
appaloft deployments timeline <deploymentId> --follow --json

HTTP/API steps

Automation systems should call through the same business operations rather than reinventing a separate set of input semantics:

curl -X POST https://your-appaloft-host/api/deployments \
  -H "Authorization: Bearer $APPALOFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "res_xxx",
    "source": { "type": "git", "url": "https://github.com/you/app" }
  }'

Full routes and input/output shapes are in the HTTP API reference; you can also inspect the running instance’s /api/openapi.json or /api/reference (Scalar) directly.

Expected output and status

A successful deployment moves through lifecycle states such as pending → planning → building → deploying → verifying → healthy (the exact values are governed by Status And Events) and ultimately returns:

the resource and target server the deployment belongs to;
the source commit / image digest, runtime, and network configuration used;
a reachable, generated access URL;
a reference to a diagnostic summary you can use for troubleshooting.

Verification

Open the returned access URL and confirm the app responds correctly.
Run appaloft resource health <resourceId> --checks --public-access-probe to confirm the health check and the public access probe both pass.
Run appaloft resource show <resourceId> --json to confirm the resource is healthy and points to the expected deployment.

Rollback / recovery

If the deployment fails or the health check doesn’t pass:

# See the failure reason and available recovery options
appaloft deployments recovery-readiness <deploymentId>

# Retry the same deployment
appaloft deployments retry <deploymentId>

# Roll back to a known-good historical deployment
appaloft deployments rollback <deploymentId> --candidate <candidateDeploymentId>

See Rollback And Recovery for the full recovery flow.

Troubleshooting links

If an AI agent is running this flow, install the Full Appaloft Skill first, then follow the Agent Deploy Subprotocol to call the entrypoints above — rather than bypassing them to operate the database or the server directly.