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 - Server output with filtering, search, time-range queries over persisted history, 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 are read when you open the tab and whenever you click Refresh; they do not poll in the background. Collecting them queries the Docker daemon, which can take several seconds on a host with a large image or build cache, so the reload runs on demand rather than on a timer.

Next to Refresh, the header reports how old the figures are - Updated just now, Updated 45s ago, Updated 12m ago. It turns amber once the reading is more than five minutes old, and reads Refreshing... while a reload is in progress. The values already on screen stay visible during a reload.

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 Users - Count of users who currently have CoderFlow open in a browser

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, task, user, exposed ports, created time, and per-container actions.

Every column header is sortable - click it to sort, click again to reverse.

The Task column names the task a container belongs to and links to its task page. When the container still carries a task ID but the task record itself is gone, the column shows the bare ID instead, since there is no task page left to open. Containers that are not task containers at all, such as interactive sessions, show a dash.

The User column names who the container was built for. This is normally the person who launched it, which is not always the person who owns the work - launching someone else's objective attributes the container to the launcher. A follow-up submitted after the container was created re-attributes it to whoever sent the follow-up.

Two cases resolve differently:

• No user recorded on the container, as with automation launches, falls back to the creator stored on the task.
• A recorded user who has since been deleted shows the raw user ID, unless the task's stored creator is that same user, in which case their details are used. The table deliberately does not substitute a different person's name.

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 Users

The Active Users card counts the people who currently have CoderFlow open in a browser, not the number of stored logins. Every CoderFlow page checks in with the server about once a minute, and a page reports itself as closed when you navigate away or close the tab, so someone who signed in yesterday and closed their browser is not counted. Several tabs or windows belonging to the same person count as one user, and CLI or API traffic is never counted.

The drilldown lists each active user with their username, name, when their current stretch of browser activity began, and how long ago their browser last checked in. A user drops off the list once their browser has been silent for three minutes, which covers cases like a closed laptop or a dropped network connection where the browser never got the chance to report itself as closed.

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 server output from two places. Recent entries come from an in-memory buffer, which holds 5,000 entries by default. Older entries come from persisted log history, which CoderFlow writes to daily files under server-logs/ in the server data directory and keeps for 14 days by default. Because the history is on disk, log queries reach back well beyond the buffer and survive a server restart. The UI loads entries for the active query and keeps up to 1,000 entries visible while live output is appended.

Retention is set with the SERVER_LOG_RETENTION_DAYS environment variable, and persistence can be turned off entirely - see Server Log Retention.

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 the current query
• Clear Display - Clear only the entries currently shown in your browser

Log Time Ranges

The range buttons choose how far back a query reaches:

• Recent - The tail of the in-memory buffer, which is the default view
• 1h, 6h, 24h, 3 days, 7 days - A window ending now
• Custom - A From and To pair of date-and-time fields, applied with Apply Range

For a custom range, leave From empty to search from the start of retained history, or leave To empty to search up to now.

Below the toolbar, the meta line reports what you are looking at: how many entries matched, the window they cover, whether they came from the memory buffer or persisted history, the sort order, and how long history is retained.

Any range other than Recent is a historical query, which does not mix with live tailing:

• Choosing a historical range while live tailing is on stops the stream.
• Choosing Start Live while a historical range is selected switches back to Recent.

A range that reaches further back than the buffer holds is served from persisted history automatically. If persistence is disabled, queries are limited to what the buffer still holds.

Inspecting and Copying Entries

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 affects only your browser - it does not clear the server-side buffer or the persisted log history.

Usage Statistics

The Usage tab summarizes task activity across loaded task history.

Start by choosing a period:

• 1 day - A rolling 24-hour window, shown as "Last 24 hours" in the period summary
• 7 days
• 30 days (the default)
• 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
• Containers - The current run state of the task containers created in this period: running, stopped, paused, removed, or unknown. Removed means the Docker daemon no longer knows the container; unknown covers containers whose state has not been determined yet. Tasks that never had a container are not counted.
• By Type
• By Environment
• By User
• By Source
• Code Impact

Note that Containers reports state as it is now, while every other breakdown describes the tasks created during the period. A 90-day view will show most containers as removed simply because they have since been cleaned up.

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, container state, 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?

Customizing the Dashboard

Use Customize to choose which breakdown sections appear. Toggle any card off to hide it and on to bring it back. Your choice is stored in your browser, so it applies to you rather than to everyone on the server.

At least one card always stays visible - the last remaining card cannot be hidden.

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 Users 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.