Skip to main content

Server Operations & Monitoring

Server Admins use Server Administration to watch host health, inspect server logs, review task usage, clean up Docker resources, and manage server updates.

Open it from the admin menu by choosing Server Administration. The page has three tabs:

  • Health - Infrastructure metrics, update controls, and Docker cleanup actions
  • Logs - Buffered server output with filtering, search, selection, copy, and live tailing
  • Usage - Task volume, success rate, code impact, duration, and drilldowns

Only the basic /health endpoint is public, for uptime checks. Detailed health metrics and drilldowns, logs, usage statistics, cleanup operations, update installs, and restart actions require Server Admin access.

Health Dashboard​

The Health tab shows the current state of the CoderFlow host and its Docker runtime.

Metrics refresh automatically every 30 seconds when Auto-refresh every 30 seconds is enabled. Turn off the toggle when you are inspecting a drilldown or comparing values manually, then click Refresh when you want a fresh read.

The top-level cards include:

  • CPU Usage - System CPU utilization since the previous measurement
  • Memory Usage - Used memory, total memory, and percentage used
  • Disk Usage - Root filesystem usage on the CoderFlow host
  • Docker Containers - Running containers compared with total containers
  • Docker Storage - Docker object storage with images, containers, volumes, and build cache broken out separately
  • Server Uptime - Current CoderFlow server process uptime
  • Active Sessions - Count of active web sessions

Status bars turn warning or critical as usage climbs. Docker storage can show either host capacity usage or logical Docker object usage, depending on what the server can read from the Docker data root. On Docker Desktop or WSL-style installs, the dashboard may show a configured limit or logical usage instead of an exact free-space percentage.

Metric Drilldowns​

Click a metric card to open its details modal.

System Information​

The CPU, memory, disk, and uptime cards open System Information. Use this when you need host facts while debugging a server issue:

  • Hostname, platform, architecture, and kernel release
  • Node.js version and server process ID
  • CPU model, core count, and per-core speed when the core list is small enough to display
  • Total and free memory
  • System uptime, process uptime, and load averages

Docker Containers​

The Docker Containers card opens a container table with name, image, status, exposed ports, created time, and per-container actions.

Use the modal actions when a specific container is clearly stale:

  • Stop - Stop a running container while leaving it on disk
  • Remove - Stop if needed, then remove the container

Removing a container does not delete the task record, logs, or generated output, but it does remove the interactive container environment for that task.

Docker Storage​

The Docker Storage card summarizes:

  • Images
  • Containers
  • Volumes
  • Build cache
  • Total estimated size
  • Estimated reclaimable space
  • Available space, when the Docker data root can be inspected

The storage drilldown lists Docker images and volumes. Use it to identify large images, old image tags, and unused volumes before running broader cleanup.

Active Sessions​

The Active Sessions card lists active session files with session ID, user, created time, and last access time. Use it to check whether operators are currently connected before restarting the server or stopping containers.

Server Updates​

The Health tab also shows Server Version.

Click Check for Updates to compare the running server version with the latest published @profoundlogic/coderflow-server package. When a newer version exists, the page shows the latest version and an install command you can copy.

Web-managed update actions are controlled from Server Settings -> Update Management:

  • Enable Web Updates - Allows Server Admins to run updates and restarts from Server Administration
  • Update Command - Command used to install a selected version. Use {version} as the placeholder for the version chosen from the Health tab.
  • Restart Command - Optional command used to restart the server after an update

When web updates are enabled and an update is available, Update Server runs the configured update command and shows command output in the page. Restart Server opens a confirmation dialog and then waits for the server to come back online.

If Restart Command is empty, the web restart action sends SIGTERM to the server process. Run CoderFlow under a process manager, such as the built-in daemon mode, systemd, or PM2, so the process starts again after that signal.

Server Logs​

The Logs tab reads the server's in-memory log buffer. The server keeps a 5,000-entry buffer by default. The UI loads recent entries for the active query and keeps up to 1,000 entries visible while live output is appended.

Use the toolbar to narrow what you are inspecting:

  • All / Debug / Info / Warn / Error - Filter by severity
  • Oldest first / Newest first - Change display order
  • Search logs - Debounced text search across the message and structured context
  • Start Live - Open a live stream of new log entries
  • Refresh - Reload from the buffered server log
  • Clear Display - Clear only the entries currently shown in your browser

Log entries can include structured context. Expand Context on an entry to inspect it.

For incident notes or support handoff:

  1. Filter or search until the relevant entries are visible.
  2. Use the checkbox on each entry, or Select All Shown.
  3. Click Copy Selected.

The copy action includes timestamp, severity, message, and context. Clear Display does not clear the server-side buffer.

Usage Statistics​

The Usage tab summarizes task activity across loaded task history.

Start by choosing a period:

  • 7 days
  • 30 days
  • 90 days
  • All time

Then optionally choose an Environment. The period and environment filters apply to every summary, table, chart, and drilldown on the page.

The summary cards show:

  • Total Tasks - All non-objective tasks in the selected scope
  • Success Rate - Completed tasks divided by completed, failed, and interrupted tasks
  • Net Lines - Lines added minus lines deleted
  • Duration - Average completed-task duration, with median and total duration in the detail text

The breakdown sections show:

  • By Status
  • By Type
  • By Environment
  • By User
  • By Source
  • Code Impact

Click a status bar, table row, or code-impact action to open the usage drilldown drawer. The drawer lists matching tasks newest first and includes environment, user, source, type, created time, duration, finished time, approval state, pushed state, file count, repository count, and code impact.

Use drilldowns when you need to answer questions like:

  • Which failed tasks happened in the last 7 days?
  • Which environment is creating the most task volume?
  • Which approved tasks changed code but have not been pushed?
  • Which tasks came from automations or integrations instead of manual creation?

Cleanup Operations​

The Clean Up section is collapsed by default on the Health tab. Expand it when host resources need immediate attention.

Stop All Containers​

Use Stop All Containers when the host is under pressure or you need to stop every running container before maintenance.

This gracefully stops every running container visible to the Docker daemon that CoderFlow is connected to, not only CoderFlow task containers. Use it carefully on shared Docker hosts. Active coding sessions, terminals, code-server windows, and app-server sessions will disconnect. Task records and output remain available.

Remove Stopped Containers​

Use Remove Stopped Containers after review work is complete and stopped containers are no longer needed for interactive inspection.

This deletes all stopped containers. It frees disk space, but those task containers cannot be restarted afterward.

Docker System Prune​

Use Docker System Prune when Docker object storage is growing and targeted cleanup is not enough.

The web action runs Docker prune operations for containers, images, networks, and volumes. It is broader than removing stopped containers and can remove unused Docker resources that are unrelated to a specific task.

The storage card still reports build-cache usage. If build cache remains high after a web prune, run your organization's standard Docker builder cleanup command on the host.

Reverse Proxy Notes​

When CoderFlow runs behind nginx, Apache, Cloudflare, or a load balancer, enable trusted proxy handling so the server reads forwarded HTTPS and client-IP headers correctly.

You can enable it in either place:

  • Set TRUST_PROXY=true in the server launch environment.
  • Open Server Settings -> General Settings, enable Trust Proxy, save, and restart the server.

Trust proxy is important for HTTPS-aware OAuth callback URLs, generated absolute URLs, secure-cookie behavior, and accurate client IPs in audit logs. If you use the Web UI toggle, the value is stored in the server CLI config and takes effect after restart.

For initial server setup and process-manager examples, see Installation.

Operational Checklist​

  • Check Active Sessions before restarting the server or stopping all containers.
  • Use Logs filters first, then copy selected entries for incident notes.
  • Prefer Remove Stopped Containers before Docker System Prune when you only need to clear reviewed task containers.
  • Keep update management disabled unless the server's process manager and update command are tested.
  • Enable Trust Proxy before configuring OAuth providers on a reverse-proxied HTTPS deployment.