ops-app-server-safety

Server safety: no duplicate long-running processes

A preflight before launching dev servers, application processes, and container stacks. Discovery does not grant permission to stop a process or mutate a Compose project; use only the authority supplied by the active task.

Rule

Before launching a long-running process, establish its expected working directory, command or Compose project, and port or service when known. Reuse an already-running matching instance unless the task requires a restart or a configuration/image change. Never stop a process merely because its name or port looks similar.

Preflight — native processes

Applies to: dev servers like vite, next dev, nodemon, uvicorn, gunicorn, flask run, rails s, custom application servers.

1. Check the port if known.

   • macOS / Linux: lsof -nP -iTCP:<PORT> -sTCP:LISTEN
   • One line per visible listener with PID and command name. Empty output means no listener was visible at that instant; it is not durable ownership of the port.

2. Check the process by command (fallback or in addition).

   • macOS / Linux: ps -ef | grep -E 'vite|next dev|nodemon|uvicorn|gunicorn|flask run|rails s' | grep -v grep
   • If multiple projects on the host could host similar processes, disambiguate by working directory: ps -o pid,command -p <PID> and lsof -p <PID> | grep cwd.

3. Prove ownership before acting. Confirm the PID's working directory and full command. A regex match alone may belong to another project or session. A project-provided PID file or process manager is valid evidence when the repository actually uses one.

Preflight — Docker Compose

Applies to any docker compose up invocation.

1. Resolve the intended Compose file, project name, and working directory. Do not let an incidental current directory select the target.
2. Check existing containers for this compose project.
   • Run the resolved project command with ps --status running --services.
   • One or more service-name lines means those services are running. The default table output is not a valid emptiness check because it includes a header even when there are no matching containers.
3. Choose by intended change.
   • No restart or configuration change: use the running services.
   • Restart with unchanged Compose configuration: use docker compose restart [SERVICE...].
   • Changed configuration or image: use docker compose up -d [SERVICE...] with the project's normal build or pull policy. Compose reconciles changed services; restart does not apply configuration changes.
   • Use docker compose down only when removal of the project's containers and networks is explicitly intended. It is not the default restart primitive.