Servers

Servers are the foundation of your oCore infrastructure. Each server is a Linux machine (physical or virtual) that runs Docker containers hosting your Odoo instances. This page covers adding servers, verifying connectivity, monitoring health, and managing server settings.

For a conceptual overview of what servers represent in oCore, see the Concepts section.

Adding a Server

To connect a new server to oCore, you provide SSH credentials and oCore handles the rest: verifying connectivity, detecting hardware specifications, and installing the oCore agent.

Prerequisites

Before adding a server, ensure:

• The server runs a supported Linux distribution (Ubuntu 22.04+, Debian 12+, Rocky 9+, or Amazon Linux 2023)
• Docker Engine 24+ is installed (oCore can install it during provisioning)
• SSH access is available on port 22 (or your custom port)
• The SSH user has sudo privileges

Step-by-step

curl -X POST https://ocore.example.com/api/servers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-eu-1",
    "host": "203.0.113.10",
    "port": 22,
    "sshUser": "root",
    "authMethod": "key",
    "sshPrivateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
  }'

ocore server add \
  --name "production-eu-1" \
  --host 203.0.113.10 \
  --port 22 \
  --ssh-user root \
  --auth-method key \
  --ssh-key-file ~/.ssh/id_ed25519

Server Verification and Health Checks

After a server is added, oCore performs periodic health checks to monitor connectivity and resource availability.

Server Statuses

Provisioning Steps

When a server is first added, the provisioning job runs through these steps:

1. SSH Connection -- Verifies SSH connectivity with provided credentials
2. System Detection -- Reads OS name, version, kernel, and architecture
3. Hardware Detection -- Reads CPU core count, total RAM, and disk capacity
4. Docker Check -- Verifies Docker is installed and reports version
5. Agent Install -- Installs or updates the oCore monitoring agent

If provisioning fails, you can retry it from the server detail page:

curl -X POST https://ocore.example.com/api/servers/{serverId}/retry \
  -H "Authorization: Bearer $TOKEN"

ocore server retry <server-id>

Viewing Provisioning Logs

Each provisioning step records its status, message, duration, and timestamps. View them on the server detail page or via the API:

curl https://ocore.example.com/api/servers/{serverId}/provisioning-logs \
  -H "Authorization: Bearer $TOKEN"

Server Metrics

oCore collects and displays real-time metrics for each connected server:

• CPU Usage -- Current and historical CPU utilization across all cores
• Memory -- Used and total RAM with usage percentage
• Disk -- Used and total disk space for the root filesystem
• Network -- Inbound and outbound traffic rates

The server detail page also shows a capacity estimate that calculates how many Odoo instances the server can support based on available CPU, RAM, and disk.

Server Settings

You can update server details at any time from the server settings page.

Editable Fields

curl -X PUT https://ocore.example.com/api/servers/{serverId} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-eu-1-updated",
    "proxyType": "traefik"
  }'

ocore server update <server-id> --name "production-eu-1-updated" --proxy-type traefik

Deleting a Server

Deleting a server removes it from oCore management. The server itself is not affected -- Docker containers, data, and OS configuration remain intact.

curl -X DELETE https://ocore.example.com/api/servers/{serverId} \
  -H "Authorization: Bearer $TOKEN"

ocore server delete <server-id>

The server status changes to removing and a background job handles cleanup. The API returns a 202 Accepted response.

Required Permissions

Server management requires the manage:servers permission. Users with the Owner, Admin, or a custom role with this permission can add, update, and delete servers. All authenticated users with any role can view servers.

Troubleshooting

Server stuck in "provisioning" status

• Check that the SSH host and port are reachable from the oCore server: ssh -p 22 root@203.0.113.10
• Verify the SSH key or password is correct
• Check the provisioning logs for the specific failed step
• Retry provisioning from the server detail page

Server shows "unreachable"

• The server may be down or the SSH port may be blocked by a firewall
• Verify network connectivity: ping 203.0.113.10
• Check that the SSH service is running on the server: systemctl status sshd
• If the server IP has changed, update it in server settings

"Docker not found" during provisioning

• Install Docker manually: curl -fsSL https://get.docker.com | sh
• Ensure Docker daemon is running: systemctl start docker
• Retry provisioning

Capacity estimate seems wrong

• The capacity calculation uses current CPU cores, available RAM, and disk space
• If the server recently had resources added, retry provisioning to re-detect hardware
• Memory reserved by the OS and other services is accounted for in the estimate