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
• CoderFlow Data - Usage of the filesystem holding the CoderFlow data directory, with the path shown on the card
• 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.

CoderFlow Data describes where CoderFlow writes its own data - task storage, uploads, and session files - which is not necessarily the root filesystem, and is not where Docker keeps its images. Docker's own capacity is reported separately on the Docker Storage card.

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
• Capacity and free space for each filesystem holding Docker's data

Docker's image layers and its volumes can live on different filesystems. When they do, the card shows a row and a usage bar for each, and the card's overall status reflects whichever is under the most pressure. When both sit on the same filesystem, the rows collapse into one.

The measurement refreshes in the background every 10 minutes, so the reading can be a few minutes old; the card notes the age once it exceeds 15 minutes. If capacity cannot be measured - most often on a new server whose base image has not been built yet - the card reports the object sizes without a usage bar rather than showing a figure it cannot substantiate.

note

Docker's own size categories overlap, so the individual rows can add up to more than the reported total.

The build cache overlaps with image layers, because BuildKit stores both in one place; the build cache row names how much of it is shared.

On hosts using the containerd image store, the overlap is larger still: image layers, container layers, and build cache all live in one store, and Docker reports the size of that whole store under its images heading. On those hosts the card groups the three beneath a Layer store row, so it is clear they are parts of one store rather than separate totals that add up.

The images figure listed there is the space unique to each image. Layers that images share cannot be attributed to any one of them from what Docker reports, so they appear only in the store total.

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.

Automatic Cleanup

CoderFlow also reclaims Docker storage on its own when a measured filesystem comes under disk pressure. This is enabled by default.

Automatic cleanup removes dangling images, unused build cache, and unused networks. It runs at most once an hour.

It never removes tagged images, containers, or volumes:

• Tagged images include the CoderFlow base image and every environment image. Docker treats an image as unused whenever no container is running from it, which is the normal idle state of an environment - so removing unused images automatically would delete the images tasks are launched from.
• Volumes hold user data.
• Containers are reclaimed separately, on their own schedule and only once their changes are safe - see Container Lifecycle.

Reclaiming those is a deliberate choice, so use the cleanup actions above when you want them removed.

A cleanup also runs immediately if a Docker operation fails because the disk is full, which reclaims space without waiting for the next check.

Configure it under Server Settings -> Docker Storage:

Setting	Meaning
Enable Automatic Cleanup	Turn the behavior off entirely.
Trigger Level	How full Docker's filesystem must be. Warning is 75% full or under 20 GiB free; Critical is 90% full or under 10 GiB free. Both levels remove the same things; only the threshold differs.
Minimum Reclaimable	Skip cleanup unless at least this much can actually be freed, so a full disk with nothing to delete is not pruned repeatedly.

While a cleanup is running, the Health tab shows its progress and disables the manual cleanup actions. The panel records when the last automatic cleanup ran and how much it freed.

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.
• Run Docker System Prune manually when tagged images or volumes need reclaiming; automatic cleanup never removes them.
• 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.