Installation

This guide walks you through installing oCore on a Linux server using Docker Compose. By the end, you will have the oCore backend, frontend, and database running and accessible in your browser.

Prerequisites

Before installing oCore, ensure your server meets these requirements:

Requirement	Minimum	Recommended
OS	Ubuntu 20.04+ / Debian 11+ / CentOS 8+	Ubuntu 22.04 LTS
RAM	2 GB	4 GB+
Disk	20 GB	50 GB+ (more for Odoo instance data)
CPU	1 core	2+ cores
Docker	24.0+	Latest stable
Docker Compose	v2.20+	Latest stable

oCore itself is lightweight, but each Odoo instance you manage consumes additional resources on the target servers. The requirements above are for the oCore management platform only.

Install Docker

If you don't already have Docker installed, follow the steps for your operating system:

Install Docker on Ubuntu/Debian

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get install -y ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and Docker Compose
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add your user to the docker group (log out and back in after)
sudo usermod -aG docker $USER

Install Docker on CentOS/RHEL

# Install prerequisites
sudo yum install -y yum-utils

# Add Docker repository
sudo yum-config-manager --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker Engine and Docker Compose
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to the docker group (log out and back in after)
sudo usermod -aG docker $USER

Install Docker using the convenience script

# Download and run the official install script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to the docker group (log out and back in after)
sudo usermod -aG docker $USER

For other distributions, see the official Docker documentation.

Verify Docker is installed correctly:

docker --version
docker compose version

Clone and configure

Clone the repository

git clone https://github.com/oCore-sh/oCore.git
cd ocore

Create your environment file

Copy the example environment file and fill in the required values:

cp .env.example .env

Open .env in your editor and set the following required values:

.env

# Required: PostgreSQL password (choose a strong password)
POSTGRES_PASSWORD=your-secure-database-password

# Required: JWT secret for authentication (minimum 32 characters)
JWT_SECRET=your-jwt-secret-minimum-32-characters-long

# Required: Encryption key for SSH credentials (minimum 32 characters)
SSH_ENCRYPTION_KEY=your-ssh-encryption-key-minimum-32-chars

# Required: Public URL where users access the frontend
APP_URL=https://ocore.example.com

# Required: API URL the frontend uses to reach the backend
NEXT_PUBLIC_API_URL=https://ocore.example.com/api

Use strong, unique values for JWT_SECRET and SSH_ENCRYPTION_KEY. These protect user sessions and stored SSH credentials. Both must be at least 32 characters.

For a complete list of configuration options, see the Configuration Reference.

Start oCore

docker compose -f docker-compose.prod.yml up -d

This starts three services:

postgres -- PostgreSQL 16 database
backend -- Go API server on port 8080 (internal) and SSH gateway on port 2222
frontend -- Next.js dashboard

The backend automatically runs database migrations on first startup.

Access the dashboard

Open your browser and navigate to:

http://localhost:3000

You will see the oCore login page. Since this is a fresh installation, click Sign Up to create your first account.

The first user to sign up becomes the initial account. Create an organization after signing up to start managing servers.

Optional configuration

These environment variables are optional but recommended for production:

Variable	Default	Description
`ENVIRONMENT`	`development`	Set to `production` for production deployments
`SMTP_HOST`	`localhost`	SMTP server for sending emails (invitations, alerts)
`SMTP_PORT`	`1025`	SMTP server port
`SMTP_FROM`	`noreply@ocore.local`	Sender address for emails
`SMTP_USERNAME`	(empty)	SMTP authentication username
`SMTP_PASSWORD`	(empty)	SMTP authentication password
`OAUTH_GITHUB_CLIENT_ID`	(empty)	GitHub OAuth app client ID for social login
`OAUTH_GITHUB_CLIENT_SECRET`	(empty)	GitHub OAuth app client secret
`OAUTH_GOOGLE_CLIENT_ID`	(empty)	Google OAuth client ID for social login
`OAUTH_GOOGLE_CLIENT_SECRET`	(empty)	Google OAuth client secret
`SSH_GATEWAY_ENABLED`	`true`	Enable the built-in SSH gateway server
`SSH_LISTEN_ADDR`	`:2222`	SSH gateway listen address
`COOKIE_DOMAIN`	(empty)	Cookie domain for cross-subdomain auth (e.g., `.ocore.sh`)

Troubleshooting

Port conflicts

If port 3000 or 8080 is already in use:

# Check what's using the port
sudo lsof -i :3000
sudo lsof -i :8080

# Or change the ports in docker-compose.prod.yml

Docker permission denied

If you get "permission denied" errors with Docker:

# Make sure your user is in the docker group
sudo usermod -aG docker $USER

# Log out and log back in, then verify
groups | grep docker

Database connection errors

If the backend cannot connect to PostgreSQL:

# Check if postgres is running and healthy
docker compose -f docker-compose.prod.yml ps

# Check postgres logs
docker compose -f docker-compose.prod.yml logs postgres

# Verify the DATABASE_URL in your .env matches the postgres credentials

The backend depends on PostgreSQL being healthy before starting. If you see connection errors on first boot, wait a moment -- Docker Compose will restart the backend once postgres passes its health check.

# Watch all service logs
docker compose -f docker-compose.prod.yml logs -f

Next steps

Now that oCore is running, proceed to the Quick Start guide to create your organization and add your first server.