Skip to content

Quick Start

Get Eight.ly OS running on your hardware. Follow every step in order.

Before You Start

You need:

  • A machine to install on — bare metal or a VM, x86-64 (UEFI or legacy BIOS) or arm64
  • A USB drive (8 GB+) if you're installing on bare metal, or a hypervisor if you're installing in a VM
  • A network connection

You don't need Docker installed anywhere — Eight.ly OS is a full bootable image, and Docker is built in and managed for you.

A license key isn't required to install or to try Eight.ly: a fresh install starts a free 30-day trial with every feature on. See Pricing when you're ready to activate.

Step 1: Get the ISO

Download the installer image from eight.ly/download.

Step 2: Write it to a USB drive (or attach it to a VM)

Use balenaEtcher, Rufus, Ventoy, or dd to write the ISO to a USB drive. If you're installing in a VM, attach the ISO as a virtual CD/DVD instead.

Step 3: Boot from it

Boot the target machine from the USB drive (or the VM's virtual CD). You'll land on the installer's welcome screen: Install Eight.ly OS onto this machine. Nothing is written to disk until you confirm at the end.

Step 4: Walk through the installer

The installer runs through these steps, in order:

  1. Disk — pick which disk to install onto
  2. Hostname — name the machine
  3. Network — DHCP or a static IP
  4. Remote access — optionally turn on SSH and create a named admin account for it (SSH is off by default; there's no root login)
  5. Confirm — review your choices; this is the last step before anything is written
  6. Install — the installer writes the image and shows progress
  7. Reboot — eject the USB and reboot into your new install

Step 5: Open the dashboard

Find the box's IP address (check your router, or the installer showed it before reboot) and open:

http://<the box's IP>:8080

Step 6: Create your admin account

There's no seeded default login — the first screen detects that no admin exists yet and has you pick a username and password right there.

Pick a real password now

This is the only account with full admin access and there's no default to fall back on if you forget it.

Step 7: Run the setup wizard

After you log in, the setup wizard walks you through, in order:

  1. Theme — pick a look
  2. Storage — set up MergerFS pooling and SnapRAID parity (or a ZFS pool)
  3. Cache Drive — add a fast SSD/NVMe write cache that drains to your array (optional)
  4. Network Settings — reverse proxy, domain, and SSL certificates
  5. Security & Auth — authentication, roles, and access policies
  6. Backup Strategy — local or Eight.ly Backup Server backups
  7. Monitoring — optional long-term metrics, dashboards, log search, and alerts
  8. One-Click Deploy — auto-install Traefik + Authelia for remote access, or finish without deploying if you're running locally only

Step 8: Deploy your first app

  1. Pick any app from the catalog — try Plex, Jellyfin, or Portainer to start
  2. Click the blue Deploy button on the app card
  3. Choose a deployment mode:
    • Standard — the simple option. The app gets a port, you access it at http://<the box's IP>:PORT. No extra setup needed. Pick this if you're not sure.
    • Traefik — gives the app a real URL like https://plex.yourdomain.com with SSL. Requires a domain and Traefik. (Setup guide)
    • Traefik + Authelia — same as Traefik but adds a login page in front of the app
  4. Click Deploy and watch it install in real time

Deploy Modal

Your app is running. You can find it at http://<the box's IP>:PORT — the port number is shown in the app card.

What Now?

You've got Eight.ly OS running. Here's what to explore next:

Something Not Working?

I see the dashboard but no apps load

The catalog is fetched from the license-gated catalog API, not a local clone — check Settings > License and confirm your license activated successfully (or that your trial is still active). If the license server is unreachable, Eight.ly keeps running and serves whatever was already cached; new apps just won't show up until connectivity is back. See Licensing.

Containers won't deploy — "Docker socket" error

Restart the service so it picks up any change to the Docker socket:

sudo systemctl restart eightly

Permission denied on /opt/appdata

Some apps store data in /opt/appdata. Create it with the right permissions:

sudo mkdir -p /opt/appdata
sudo chown -R $USER:$USER /opt/appdata