Installation

CubyCrate is packaged as a single container image containing the Go server and embedded web interface. Deploying the container takes only Docker and a compose file.

System Prerequisites

Host architecture: Linux amd64 or arm64.
System resources: Minimum 512 MB RAM (1 GB recommended) and 1 vCPU.
Runtime: Docker Engine 24.0+ and Docker Compose v2.20+.
Network ports: Port 8383 available for HTTP traffic.

Data Directory Layout

All application state is preserved inside the container path defined by DATA_DIR_PATH (default: /app/data). Ensure this directory points to a persistent volume:

/app/data/
├── db/
│   └── cubycloud.db        # SQLite database in WAL mode
├── secrets/
│   ├── jwt.key             # Auto-generated JWT signing secret (64-char hex)
│   └── master.key          # AES-256-GCM master encryption key for node secrets
├── storage/                # Default local storage node mount point
└── temp/                   # Temporary chunks for inflight TUS uploads

Docker Compose Deployment

Create project directory

Create a dedicated directory on your server and navigate into it:
Terminal window
```
mkdir -p cubycloud && cd cubycloud
```

Create the compose file

Save the following configuration as compose.yaml:

services:
  cubycloud:
    image: ghcr.io/septian-padli/cubycloud:latest
    container_name: cubycloud
    restart: unless-stopped
    ports:
      - "8383:8383"
    environment:
      - DATA_DIR_PATH=/app/data
      - TRUST_PROXY=false
      - COOKIE_SECURE=false
    volumes:
      - cubycloud_data:/app/data
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:8383/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  cubycloud_data:

Start the container

Launch CubyCrate in detached mode:
Terminal window
```
docker compose up -d
```
Verify container health

Check the status of the container and follow the logs:
Terminal window
```
docker compose ps
docker compose logs -f cubycloud
```

First-Time Setup Wizard

Once the container is healthy, visit http://<your-server-ip>:8383/setup in your browser. The initial setup wizard guides you through five essential steps:

Welcome and prerequisites check

The system verifies that the SQLite database is writable and file permissions are valid.
Create primary administrator account

Provide an administrator username, email address, and a secure password. The password must contain at least 8 characters.
Storage node setup

Select your primary storage backend:
- Local Storage Node: Enter a name and verify the local path (defaults to /app/data/storage).
- S3-Compatible Storage: Configure your S3 endpoint, bucket name, region, and access/secret credentials.
Save the recovery key

The wizard generates a 32-character Crockford Base32 recovery key (e.g., ABCD-EFGH-JKMN-PQRT-...).

Store this recovery key in a secure location (such as a password manager). If you lose access to your administrator account, this key is the only offline method to reset administrative access.
Finalize and sign in

Confirm your settings. The setup wizard locks automatically, and the application redirects to the login screen at /login.

Next Steps

Configuration Guide: Set up production reverse proxies (Nginx or Caddy) with SSL/TLS and upload limits.
Backup and Recovery: Learn how to back up your database, master key, and storage nodes.