Servers

How oCore manages Linux servers via SSH, agent installation, and metrics collection

A server in oCore represents a Linux machine that hosts Odoo instances. oCore connects to servers via SSH to deploy containers, collect system metrics, run backups, and perform maintenance operations.

How servers work

Loading diagram...

When you add a server to oCore:

Connection -- oCore establishes an SSH connection to the server using the credentials you provide (SSH key or password).
Verification -- oCore verifies the connection, checks for Docker, and gathers basic system information (OS, CPU, memory, disk).
Agent installation -- oCore installs a lightweight monitoring agent as a systemd service on the server.
Ongoing management -- The agent continuously collects metrics and enables oCore to manage Docker containers remotely.

SSH connection

oCore uses SSH for all server communication. The connection supports:

Key-based authentication (recommended) -- Upload your private key or use an existing one. oCore encrypts stored SSH keys using the SSH_ENCRYPTION_KEY environment variable.
Password authentication -- Supported but not recommended for production use.
Custom port -- Connect to SSH on any port (default: 22).

oCore includes a built-in SSH gateway that proxies terminal sessions to managed servers. Users can connect through the gateway using their oCore credentials without needing direct SSH access to the server.

SSH gateway

The SSH gateway listens on port 2222 (configurable via SSH_LISTEN_ADDR) and allows authenticated users to access terminal sessions on managed servers. The gateway:

Authenticates users via their oCore JWT token
Verifies RBAC permissions for the target server
Proxies the SSH session to the target server using the stored credentials
Logs session activity for audit purposes

Monitoring agent

The oCore agent is a lightweight service installed on each managed server. It collects:

Metric category	Metrics collected
CPU	Usage percentage, load average (1m, 5m, 15m), core count
Memory	Total, used, available, swap usage
Disk	Total, used, available per mount point
Network	Bandwidth in/out, connection count
Docker	Container count by state, per-container CPU/memory

Metrics are reported to the oCore backend at regular intervals and stored for historical dashboards and alerting.

Server lifecycle

Loading diagram...

Status	Description
Connecting	Initial SSH connection attempt
Connected	SSH connection established, awaiting agent installation
Provisioning	Agent being installed on the server
Active	Server is fully managed, metrics flowing, ready for deployments
Failed	Connection failed (credentials, firewall, SSH configuration)
Removing	Server being cleaned up (async delete)

Deleting a server is an asynchronous operation. oCore sets the server status to "removing", returns immediately, and a background worker handles cleanup -- removing the agent, disconnecting SSH, and cleaning up references. Active instances on the server should be migrated or stopped first.

Server requirements

Before adding a server to oCore, ensure it meets these minimum requirements:

Requirement	Details
Operating system	Ubuntu 20.04+, Debian 11+, CentOS 8+, or any modern Linux with systemd
SSH access	Root or sudo-capable user
Docker	Docker Engine 24.0+ installed and running
Network	Accessible from the oCore host on the SSH port
Resources	At least 1 GB RAM and 10 GB disk per Odoo instance you plan to run

Port allocation

oCore allocates network ports for Odoo instances automatically. Each instance receives:

Port	Purpose	Offset
Base port	Odoo web interface	+0
Longpolling port	Odoo longpolling (live chat, notifications)	+1
Mailpit port	Development email testing (Mailpit)	+2

Port allocation starts at base 10000 with a gap of 10 between instances (10000, 10010, 10020, etc.). This gap allows for future expansion of per-instance services without port conflicts.

Health checks

oCore performs regular health checks on managed servers to detect issues proactively:

SSH connectivity -- Verifies the SSH connection is still active
Docker daemon -- Checks that Docker is running and responsive
Disk space -- Alerts when disk usage exceeds configurable thresholds
Agent status -- Verifies the monitoring agent is running and reporting

Health check results are visible in the server detail page and can trigger alert notifications.