Docker Installation

Prerequisites

• A Linux server (Ubuntu, Debian, etc.)
• Docker Engine installed and running
• Docker Compose plugin (or standalone docker-compose)
• openssl or htpasswd (from apache2-utils) — used to generate credentials during installation
• Root or sudo access

Step 1: Run the Installer

Run the install command with the docker argument appended:

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/Magenta-Mause/Cosy/v1.0.3/install_cosy.sh)" _ docker

The script will display the COSY ASCII logo and launch the interactive installer.

Step 2: Installation Path

Installation path [default: /opt]:

This is where COSY will store its configuration and game server data. The script creates a cosy/ subdirectory inside this path (e.g., /opt/cosy).

Press Enter to accept the default /opt, or enter a custom <installation-path>.

Step 3: Admin Username

Admin username [default: admin]:

This is the username for the initial owner account. Press Enter to use admin, or type a custom name.

Step 4: TLS / HTTPS

Enable TLS/HTTPS via Let's Encrypt? [y/N]:

Choose whether to enable automatic HTTPS. When enabled, COSY uses Caddy as its reverse proxy, which automatically obtains and renews TLS certificates from Let's Encrypt.

Requirements for TLS mode:

• A domain name pointing to your server (not an IP address)
• Ports 80 and 443 must be available
• An email address for Let's Encrypt notifications

If you enable TLS, you'll be prompted for the Let's Encrypt email:

Email for Let's Encrypt notifications:

Note: TLS mode cannot be combined with a custom port. When TLS is enabled, the port prompt is skipped and COSY listens on the standard HTTPS port (443).

Step 5: Port (non-TLS only)

Port [default: 80]:

This prompt only appears when TLS is not enabled. The port COSY's web interface will listen on. If port 80 is already in use, enter a different port.

The script validates that the port is not already in use.

Step 6: Domain

Domain [default: your-hostname]:

The domain or IP address users will use to access COSY. This is used for CORS configuration. If you're running COSY on a server with a public domain, enter it here (e.g., cosy.example.com). If you don't have a domain, you can also use the server's IP address directly. For local testing, set this to localhost.

Need a domain? Get a free subdomain at the Cosy Domain Provider — claim a *.cosy-hosting.net subdomain and point it to your server's IP address.

Step 7: Footer Information (Optional)

Footer full name [default: empty]:
Footer email [default: empty]:
Footer phone [default: empty]:
Footer street [default: empty]:
Footer city & zip code [default: empty]:

These fields populate a contact footer in the COSY UI. They're entirely optional — press Enter to skip each one. The Owner can change these values later through the COSY UI.

Note: Depending on your jurisdiction, you may be required to provide legal contact information (e.g., an imprint) for publicly accessible services. Check your local regulations and fill in the relevant fields if needed.

What Happens Next

After you answer the prompts, the script automatically:

1. Runs pre-flight checks — Verifies Docker, Docker Compose, and port availability
2. Creates the directory structure — <installation-path>/cosy/config and <installation-path>/cosy/volumes
3. Generates credentials — Random 30-character passwords for PostgreSQL, InfluxDB, Loki, and the admin account
4. Downloads config files — docker-compose.yml, nginx configs, and Loki config from GitHub
5. Writes the .env file — All configuration in a single environment file
6. Starts all services — Runs docker compose up -d and waits for health checks to pass
7. Installs a systemd service — COSY starts automatically on boot

Step 8: Save Your Credentials

When the installation finishes, you'll see:

╔═══════════════════════════════════════════════════════════╗
║          COSY installation completed successfully!        ║
╚═══════════════════════════════════════════════════════════╝

  Installation path:  /opt/cosy
  Deployment method:  docker

  ── Login Credentials ──────────────────────────────────
  Username:           admin
  Password:           <randomly-generated-password>

  ── Access URL ────────────────────────────────────────
  COSY:               http://your-domain:80

  ⚠  Please save the password above - it will not be shown again.

Save the password. It's randomly generated and also stored in the config/.env file inside your installation directory alongside all other configuration values.

Accessing COSY

Open the access URL shown in the installer output in your browser (https://<your-domain> for TLS or http://<your-domain>:<port> without TLS) and log in with the admin credentials.

Services

The Docker Compose stack runs 7 services:

Managing COSY

# Stop COSY
sudo systemctl stop cosy

# Start COSY
sudo systemctl start cosy

# Restart COSY
sudo systemctl restart cosy

# Check status
sudo systemctl status cosy

Viewing Logs

COSY uses the journald logging driver:

# Backend logs (live)
journalctl CONTAINER_NAME=cosy-backend -f

# All COSY containers
journalctl CONTAINER_NAME=cosy-backend CONTAINER_NAME=cosy-frontend CONTAINER_NAME=cosy-nginx -f

# Last 50 backend log lines
journalctl CONTAINER_NAME=cosy-backend -n 50