Install with the Script

The install script creates a production Docker Compose deployment from prebuilt CoreCube images. It writes the Compose file, generates strong local secrets, creates the object-storage configuration, pulls images, and preserves existing .env and s3.json files when run again.

Use this path when you want the fastest self-hosted setup. Use Docker Deployment when you want to build the Compose file manually or review every service definition.

Prerequisites

• Docker Desktop or Docker Engine with the docker compose plugin
• curl
• openssl
• python3

On Linux servers, your user must either be in the docker group or run Docker commands with sudo. On Windows, run the installer inside WSL2, not in PowerShell or Command Prompt.

Linux

Run the installer from the directory where you want the corecube/ folder created:

# Go to the parent path where CoreCube should be installed, for example /opt, /srv, or ~/apps.
cd /opt

curl -fsSL https://corecube-data.pages.dev/install.sh | sudo bash

Use sudo for root-owned locations such as /opt or /srv. For a user-owned path such as ~/apps, run it without sudo:

mkdir -p ~/apps
cd ~/apps

curl -fsSL https://corecube-data.pages.dev/install.sh | bash

The installer prompts for a folder name. The default is corecube.

macOS

Apple Silicon

The script-based deployment uses Linux Docker images. If the published images are not available for linux/arm64, Docker Desktop on Apple Silicon must run the linux/amd64 images through Rosetta.

In Docker Desktop, enable both settings under Settings -> General:

• Apple Virtualization framework
• Use Rosetta for x86_64/amd64 emulation on Apple Silicon

Then install into a user-owned directory and pass the platform override to bash:

mkdir -p ~/apps
cd ~/apps

curl -fsSL https://corecube-data.pages.dev/install.sh | DOCKER_DEFAULT_PLATFORM=linux/amd64 bash

Do not run this command with sudo; sudo can strip environment variables, which prevents the platform override from reaching Docker. Inference runs under Rosetta emulation, so this is suitable for testing and evaluation, not for production performance benchmarking.

MPS

Docker Desktop cannot expose Apple Metal/MPS to Linux containers. MPS inference is only available when the inference services run as native macOS Python processes from a source checkout.

For that workflow, use the source repository and run:

make deploy-local-mps

The install script does not enable MPS acceleration.

Windows

Use Docker Desktop with the WSL2 backend, then run the installer from a Linux shell inside WSL2.

Recommended flow:

mkdir -p ~/apps
cd ~/apps

curl -fsSL https://corecube-data.pages.dev/install.sh | bash

Keep the install directory inside the WSL Linux filesystem, for example under ~/apps, rather than under /mnt/c/.... Docker bind mounts and file permissions are more reliable there.

Installer prompts

On a fresh install, the script asks for:

• Install folder name, defaulting to corecube
• CoreCube image tag, defaulting to latest
• CUDA inference on Linux if an NVIDIA GPU is detected
• Whether to enable the bundled Caddy reverse proxy for HTTPS

During setup, you can answer n to the bundled Caddy prompt when you are only using CoreCube on localhost. Use HTTPS when exposing CoreCube to another device or host. Browser features used by the Admin Console require a secure context, which means HTTPS or localhost.

Start CoreCube

After installation:

cd ./corecube

# Review .env before first start. At minimum set CUBE_ADMIN_EMAIL and CORECUBE_PUBLIC_URL.
docker compose up -d

If your Docker installation requires elevated privileges, run sudo docker compose up -d.

Follow startup logs:

docker compose logs -f corecube

URLs

Service	URL
Admin Console	http://localhost:7400/admin
Headless API	http://localhost:7400/v1
OpenAPI spec	http://localhost:7400/v1/openapi.json
Interactive API docs	http://localhost:7400/v1/docs
Open WebUI	http://localhost:3000
s3storage S3 API	http://localhost:8333
s3storage Master UI	http://localhost:9333
s3storage Filer UI	http://localhost:8888

Default login

The default admin login is:

Field	Value
Email	admin@example.com
Password	changeme123

Change the password immediately after first login.

Upgrade

Run the installer from inside the existing install directory:

cd ./corecube
curl -fsSL https://corecube-data.pages.dev/install.sh | bash
docker compose up -d

Existing .env and docker/s3storage/s3.json files are preserved. If docker-compose.yml changes, the old file is saved as docker-compose.yml.bak.

To refresh container images without replacing the Compose file:

docker compose pull
docker compose up -d

Stop

docker compose down

Linux NVIDIA GPU

For GPU-accelerated inference on Linux, set these values in .env:

INFERENCE_IMAGE_TAG=cuda-latest
INFERENCE_DEVICE=cuda

Then uncomment the deploy.resources GPU reservation block for both inf-embedding and inf-reranker in docker-compose.yml.

See Docker Deployment -> NVIDIA GPU for the full Compose snippet.