Requirements and planning

Plan the control plane separately from the hosts that run customer workloads. Opfield coordinates identity, desired state, certificates, operations, and audit history; it does not remove the need to size, patch, back up, and monitor the underlying Linux hosts.

Opfield is a privileged control plane

The Opfield host has access to encrypted infrastructure credentials and a writable Docker socket used for signed updates, recovery, housekeeping, and local managed services. Control of this host is effectively root-level control over the Opfield installation and can affect every connected resource within its authorized scope. Use a dedicated VM or host, place it in a restricted management network, and do not share it with unrelated workloads.

Decide the deployment shape

A small evaluation can place the Opfield application and its internal services on one Linux host. Production environments should still treat that host as a control-plane dependency with explicit ownership, durable storage, a recovery procedure, and monitored capacity. Managed workload roles can be enrolled later and may live on separate physical hosts, virtual machines, or appropriately isolated system containers.

Before installation, record:

• the canonical HTTPS URL users and managed nodes will trust;
• who owns DNS, certificates, authentication, backups, and upgrades;
• which networks may reach the web application and Relay;
• which node roles are needed immediately and which can be added later;
• the required product plan and feature entitlements;
• the recovery objective for Opfield data and encryption material.

Avoid designing around temporary IP addresses or a hostname that will be renamed after onboarding. The canonical URL participates in browser security, redirects, generated commands, and integrations.

Host and capacity decision

Provide a supported Linux host with root access or working sudo. Docker is not a prerequisite for the public installer: when Docker Engine or the Compose v2 plugin is absent, the installer installs and configures them from Docker’s official package repositories. Automatic Docker installation supports Debian, Ubuntu, Fedora, CentOS, and RHEL families. If Docker is already present, the installer validates that the engine is reachable and Compose v2 is available.

Use these base sizing profiles for the control plane:

Profile	CPU	Memory	Free SSD capacity
Minimum	2 vCPU	4 GB RAM	32 GB
Recommended	4 vCPU	8 GB RAM	64 GB

The disk figures are free capacity after the operating system is installed. Opfield-managed local ClickHouse logging needs an additional 32 GB minimum or 128 GB recommended; actual usage depends on ingest volume and retention. External ClickHouse does not add local logging storage to the Opfield host.

Reserve persistent storage for Opfield PostgreSQL data, Redis persistence where configured, uploaded artifacts, certificates, configuration, the internal registry, and optional structured logs. Git-source builds need additional registry capacity because successful, active, rollback, in-progress, and manually pinned artifacts are retained. Opfield’s own containers—the application, Relay, registry, PostgreSQL, and Redis—keep at most three 50 MB log files each; an update adds this limit to existing installations unless a service already has its own logging configuration.

At minimum, ensure that the host also has:

• enough headroom for the application, PostgreSQL, Redis, and Relay without sustained swap pressure;
• durable storage with free-space monitoring and a tested backup destination;
• correct system time and reliable DNS resolution;
• an operating system update process that does not silently replace persistent volumes;
• access to the current signed Opfield release and license service.

Do not store the only copy of the backup or encryption key on the Opfield host. A database backup without the corresponding secret-encryption material is not a complete recovery set.

Operator detail: network access

The public installation normally needs inbound HTTP/HTTPS for the user interface and API. Managed nodes connect through Relay, which requires reachable 9443/tcp when nodes are outside the local network. Restrict administrative access at the network edge when possible, but do not place a proxy or firewall in the Relay path unless it supports the required long-lived connections.

Outbound access depends on enabled features. Typical destinations include identity providers, ACME and DNS providers, source-control systems, container registries, release and license services, email/webhook endpoints, SIEM receivers, and configured AI providers. Build Workers may need a different and more restrictive egress policy than the control plane.

Some Node roles need more:

• Storage Nodes pull the backup runner from GitHub Container Registry, so they need outbound HTTPS to ghcr.io. Managed engines (SeaweedFS, PostgreSQL, Redis, ClickHouse) and the Compose sidecar of Docker Nodes are pulled by digest from the Opfield mirror on ghcr.io first, with Docker Hub as a fallback.
• Workload Availability in lease mode: every Docker Node of a policy and every Ingress Node of its Routes must reach every Relay of the pool on its advertised port; see Data-plane failover.

Review Ports and network before changing firewalls. Validate paths from the actual host and network namespace that will initiate the connection; a successful request from an administrator laptop is not evidence that Opfield or a node can reach the same endpoint.

Node roles and trust boundaries

Choose only the roles you need:

• nginx node: ingress, TLS materialization, Pages, access/error logs, and traffic metrics;
• Docker node: Containers, Deployments, Compose Projects, files, logs, and runtime health;
• Storage Node: managed PostgreSQL, Redis, or ClickHouse instances, managed object storage, their durable storage, and database backup jobs;
• Build Worker: isolated BuildKit/containerd execution without exposing a Docker Engine socket;
• monitoring node: monitoring-specific collection for supported targets;
• Relay Pool member: additional Secure Link data-plane capacity and resilience.

Storage Node and Docker Node prerequisites

A Storage Node runs the Docker daemon as root and keeps every managed database, object storage cluster, and backup workspace in a fixed-size ext4 image on a loop device, so its disk use is bounded. The installer checks this before enrollment: it formats, mounts, grows, and detaches a test image and stops if the host cannot. Each managed database, object storage member, and running backup holds one loop device while it exists. Virtual machines and physical hosts create loop devices as needed. An LXC guest works only when its host passes /dev/loop-control and a pool of loop devices and allows loop block devices and mounts; size that pool for every managed instance and concurrent backup the Node will hold. When the pool is exhausted, creating an instance fails with node has no free loop device; the daemon releases the devices of deleted instances by itself.

On a Docker Node, a managed disk-image volume also holds one loop device. For data-plane failover, each Docker Node that can hold an Availability lease runs the lease watchdog as a root service under systemd or OpenRC; the Docker node installer installs it.

A Docker Node also needs Docker to give its containers the memory, pids, and cpu cgroup controllers; the installer refuses to enroll the Node otherwise. An Alpine LXC guest with OpenRC usually needs a cgroup setup first; see Alpine, OpenRC, and LXC guests. A Build Worker needs systemd. Monitoring, Docker, nginx, and Relay daemons can run without root; see Run a daemon without root.

Role separation is an operational and security decision. A Storage Node should have storage and backup policies appropriate for stateful services. A Build Worker processes repository-controlled build input and should not share a host with unrelated workloads or reusable infrastructure credentials. Treat the worker’s outer VM or unprivileged system container as the security boundary; the inner build sandbox is defense in depth, not the only boundary.

A Docker Node normally needs control of the local Docker Engine. Anyone who controls that daemon path can create privileged containers, mount host paths, and affect other workloads on the same engine. Treat a Docker Node as root-equivalent within that host’s Docker trust boundary; use a dedicated host or deliberately accepted workload boundary rather than assuming resource scopes isolate a compromised host administrator.

DNS and certificates

Decide whether Opfield will manage DNS through Cloudflare or whether records remain externally managed. HTTP-01 certificate issuance requires public port 80 on the assigned ingress node. DNS-01 requires a configured provider integration with the minimum permissions necessary to create challenge records. Uploaded certificates require an owner for renewal and expiry monitoring.

Use a hostname already covered by a trusted certificate for the initial Opfield URL. Browser warnings during bootstrap encourage unsafe workarounds and can obscure real proxy or hostname problems.

Readiness checklist

Before running the installer, confirm all of the following:

1. The canonical hostname resolves to the intended endpoint.
2. TLS termination and forwarded-header ownership are documented.
3. Persistent storage and an off-host backup destination exist.
4. Firewall rules cover the web application, Relay, and required outbound services.
5. The first administrator and a second recovery owner are identified.
6. Node roles and host isolation are intentional.
7. Retention, audit, notification, and SIEM expectations are documented.
8. Required plan entitlements are available.

If one of these decisions is unknown, stop before onboarding production workloads. It is much safer to change topology, DNS, or authentication before nodes and integrations depend on them.

See Ports and network before changing firewalls.