Operating a server

Running a LoonFS server

A LoonFS server runs maintenance automatically for namespaces touched by that process. “Quiet” namespaces can be assigned explicitly so they initiate maintenance even when no client traffic is initiated organically.

Alternatively, embedded deployments should initiate background work explicitly.

Types of maintenance work

Compaction, indexing, and garbage collection are the categories of background work used in LoonFS. See Background jobs.

Maintenance API

Every active namespace requires regular metadata maintenance. A normally configured LoonFS server schedules work automatically for the assigned namespaces.

For an embedded or manually maintained deployment, keep maintenance loop running or invoke it with --drain on a regular schedule (maintenance loop itself is embedded-only).

• maintenance loop — host maintenance continuously, or use --drain to catch up and exit

The maintenance CLI also exposes granular, one-off controls:

• maintenance metadata — run one metadata-maintenance pass
• maintenance gc — run one complete mark-and-sweep garbage-collection pass
• maintenance grep-gc — clean up search-index objects that are no longer used
• maintenance flush — flush pending WAL work
• maintenance retention advance — explicitly advance the retention floor
• maintenance checkpoint create — create a durable pin of the namespace’s current state. See Checkpoints.
• maintenance checkpoint list / maintenance checkpoint delete — list and delete checkpoint pins
• maintenance index enable — enable and begin the backfill for the content index used by Search, with maintenance index disable and maintenance index status alongside it
• maintenance store probe — verify the configured object store’s set of capabilities

Run loonfs maintenance --help before using these in production.

Monitoring and tuning

Deployment-specific limits can also be set, and can be expected to be tuned over time based on query patterns and other factors: Limits.

GET /v0/maintenance/namespaces/{namespace_id}/diagnostics returns the namespace state and storage details used by maintenance:

Field	Meaning
namespace_id	Namespace being inspected.
head_seq	Current visible namespace sequence.
retention_floor_seq	Oldest sequence still promised for incremental replay.
current_manifest_no	Current manifest number; omitted until a manifest exists.
wal_tail_segments	Visible WAL segments after the current manifest.
live_snapshots	Snapshots whose leases had not expired when diagnostics began.
live_checkpoints	Active user checkpoints, including expired records awaiting collection.

To get started, see Deploying a server.