Register and test a server

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 from CLI/API or the Web server detail page; 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. CLI/API and the Web server detail danger tab all use the same one-way deactivate command; the Web form requires typing the exact server id before submitting.

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; the Web server detail danger tab requires the same exact server id before it dispatches deletion.

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.

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.

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.

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 \
  --target-kind single-server \
  --proxy-kind traefik

--target-kind orchestrator-cluster records a cluster-shaped deployment target for future cluster backends such as Docker Swarm. It does not by itself make the target ready for deployments; readiness still depends on the registered runtime backend capabilities and connectivity checks.

Docker Swarm targets are registered as cluster-shaped deployment targets. Use --target-kind orchestrator-cluster --provider docker-swarm only for a Swarm manager endpoint that Appaloft can reach through the selected transport.

Current status: Appaloft can record Swarm target metadata, run non-mutating manager readiness checks through server test or server doctor, reject unsupported Swarm-specific deployment fields before a deployment is created, and execute Swarm deployments through the default runtime backend. Set APPALOFT_DOCKER_SWARM_EXECUTION_ENABLED=false only when an installation needs to disable Swarm execution explicitly; with that opt-out, deploying to a Swarm target should fail before acceptance with runtime_target_unsupported.

Keep deployment requests ids-only. Do not add Swarm fields such as namespace, stack name, service name, replicas, update policy, ingress, registry secret, or manifest directly to deployments.create or appaloft.config.*. If a validation error names one of those fields, remove it and use the supported resource, environment, and server inputs for the current runtime target.

Before deploying to a Swarm target, server test/server doctor checks:

• the manager address is reachable through SSH;
• Docker is available on the manager;
• the endpoint reports an active Swarm manager control plane;
• the overlay network driver is available;
• the configured edge proxy is compatible with the Swarm target.

Operators should also verify:

• image registry access is configured without exposing secret values;
• the Swarm edge network is an overlay network; set APPALOFT_DOCKER_SWARM_EDGE_NETWORK when the deployment should use a network name other than appaloft-edge;
• health checks and service logs can be read in a form Appaloft can normalize.

Swarm rollout preserves the previous service until verification passes, logs and health are returned as Appaloft status shapes, and cleanup stays scoped to the resource, deployment, destination, and target labels.

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