Register and test a server

Server connectivity flow

What a server is

A server is a target Appaloft can connect to, inspect, and deploy applications onto. Users see SSH address, credential, connectivity state, runtime summary, and proxy readiness.

A server is not a project or a resource. One server can host multiple resources, and resource access still depends on network profile and proxy readiness.

Registering a server makes Appaloft able to execute deployment plans. It does not deploy an app by itself.

Reading server detail confirms a deployment target’s host, provider, masked credential summary, proxy status, and current deployment, resource, and domain rollups. This read does not run connectivity checks, repair proxy state, or mutate the server.

Renaming a server changes only the display name. It does not change server id, host, provider, credential, proxy, lifecycle, or historical deployment/domain/audit references. Active and inactive servers can both be renamed; deleted servers are not visible through the normal rename entrypoint.

Changing the edge proxy kind saves the server’s desired proxy intent for future routes. none means future generated access URLs or custom-domain routes should not treat this server as a proxy-backed target; traefik and caddy mark the server for later proxy readiness and route realization. This does not change server id, host, provider, credential, lifecycle, and it does not delete historical route snapshots, deployments, domains, or audit references. Only active servers can be changed; inactive servers do not receive new proxy target configuration work through the normal entrypoint.

Deactivating a server prevents it from being used as a new deployment, scheduling, or proxy configuration target. Deactivation does not stop existing runtime work and does not delete deployment history, domains, certificates, credentials, routes, logs, or audit records.

Before deletion, run the delete safety check. The check returns blocker reasons such as the server still being active, retained deployment history, active deployments, resource placement, domains, certificates, attached credentials, server-applied routes, default access policy, terminal sessions, runtime tasks, logs, or audit retention. The check is a preview and does not delete anything.

Server deletion is only for a deactivated server with no blockers. Deletion removes the server from normal list, detail, and new deployment target selection, but it does not automatically clean up deployment history, resources, domains, certificates, credentials, routes, logs, or audit records. CLI deletion requires explicit confirmation, such as --confirm srv_primary.

Connectivity test

Connectivity checks confirm that Appaloft can reach the server and read required runtime information. A failed check does not mean old deployments failed, but it should block new deployments that depend on the server.

Checks should cover:

DNS/IP and port reachability.
SSH credential validity.
User permissions required for deployment.
Basic runtime environment requirements.
Proxy or Docker diagnostics when relevant.

Registration inputs

Register host, port, user, credential source, and optional labels. Do not put resource, environment, or domain concerns into server registration.

Common inputs:

host: server address.
port: SSH port, usually 22.
user: system user.
credential: SSH key path, saved credential, or one-time secret input.
display name / labels: helps users identify the server.

Entrypoints

The Web console should guide registration and connectivity testing together. After SSH input, users should immediately see test results and next steps.

The CLI fits local SSH bootstrap because it can read local key paths and ask for confirmation.

The HTTP API fits automated server registration, but should never echo secrets. Connectivity results should be structured.

Recovery

Common failures:

Timeout: check host, port, firewall, and network.
Authentication failure: check SSH key, user, and authorized keys.
Permission failure: check whether the user can run required deployment commands.
Missing runtime: follow diagnostic instructions or select a supported provider/runtime.

After connectivity passes, continue with SSH credentials and Proxy readiness.

CLI examples:

appaloft server register \
  --name primary \
  --host 203.0.113.10 \
  --port 22 \
  --provider generic-ssh \
  --proxy-kind traefik

appaloft server test srv_primary

appaloft server show srv_primary

appaloft server rename srv_primary --name "Primary SSH server"

appaloft server proxy configure srv_primary --kind caddy

appaloft server deactivate srv_primary

appaloft server delete-check srv_primary

appaloft server delete srv_primary --confirm srv_primary