Skill/deploy-company-linux/SKILL.md

name, description

name	description
deploy-company-linux	Deploy, publish, update, inspect, or roll back Docker Compose and Dockerfile applications on the company internal Linux server at 192.168.31.51. Use when Codex is asked to deploy a local project to the company server, release a new version, check a deployed application, establish deployment SSH access, or restore the previous release.

Deploy Company Linux

Deploy applications to the company Linux host through SSH with release directories, health checks, and automatic rollback.

Workflow

1. Read references/server-profile.md before choosing ports or a deployment name.

2. Inspect the project, including AGENTS.md, Git status, Docker files, environment examples, volumes, ports, and health endpoints.

3. Prefer an existing compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml. Use Dockerfile mode only when no Compose configuration exists.

4. Derive a lowercase app name that starts with a letter or digit and contains only letters, digits, underscores, and hyphens. Do not reuse an existing application name unless the user is updating that application.

5. Detect port collisions against the server profile and a live preflight. Ask only when the intended application name, public port, or health endpoint cannot be inferred safely.

6. Check whether every Docker base image is cached before deploying. The server may be unable to reach Docker Hub; for Node.js projects, prefer the server's cached local/node:24.16.0-bookworm image when appropriate.

7. Authenticate with an SSH key. If key authentication is unavailable, use COMPANY_LINUX_PASSWORD only for the current process. Never write a password into the skill, repository, deployment archive, command output, or shell history.

8. Run preflight before deployment:

   powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1 `
     -Action preflight -AppName <app-name>
   

9. Deploy from the project root:

   powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1 `
     -Action deploy -ProjectPath <absolute-project-path> `
     -AppName <app-name> -Mode auto `
     -HealthUrl <remote-health-url>
   

10. Report the release path, containers, exposed endpoint, and health result. If the command fails, report whether automatic rollback succeeded and include the smallest relevant log excerpt.

Authentication Setup

Prefer an existing SSH key. For first-time setup, set the password only in the current PowerShell process, run the setup script, then remove it:

$env:COMPANY_LINUX_PASSWORD = Read-Host "Company Linux password"
powershell -ExecutionPolicy Bypass -File scripts/setup-ssh-key.ps1
Remove-Item Env:COMPANY_LINUX_PASSWORD

The setup script adds the current user's Ed25519 public key to /home/jsxq/.ssh/authorized_keys. Treat this as a server change and run it only when the user authorizes SSH key setup.

Dockerfile Mode

When deploying a Dockerfile without Compose, provide both ports if the application must be reachable:

powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1 `
  -Action deploy -ProjectPath <path> -AppName <name> `
  -Mode dockerfile -PublishPort 8800 -ContainerPort 8000 `
  -HealthUrl http://127.0.0.1:8800/health

Use .env as the container environment file when it exists. Do not print its contents.

Status and Rollback

Check status:

powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1 `
  -Action status -AppName <app-name>

Roll back to the previous successful release:

powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1 `
  -Action rollback -AppName <app-name>

Safety Rules

• Deploy only under /home/jsxq/apps/<app-name>.
• Keep application data in named Docker volumes or explicit shared directories. Warn before deploying Compose files that bind persistent data to source-relative paths.
• Never run docker system prune, remove Docker volumes, delete unrelated containers, modify firewall rules, or use sudo as part of the normal workflow.
• Do not deploy an unreviewed .env accidentally. Verify that it belongs to the target environment without revealing its values.
• Do not expose database, Redis, administrative, or debug ports unless the user explicitly requires it.
• Treat a production-named application or an existing public port as high impact; show the detected target before updating it.
• Preserve the previous release. The remote script automatically restores it when a supplied health check fails.

Bundled Scripts

• scripts/deploy.ps1: preflight, deploy, status, and rollback entry point for Windows/Codex Desktop.
• scripts/remote-deploy.sh: deterministic release and rollback logic executed on the server.
• scripts/setup-ssh-key.ps1: optional one-time SSH key bootstrap.
• scripts/ssh-askpass.cmd: reads the temporary password environment variable without storing a password in the file.