Server Installation

The Haloy daemon (haloyd) runs on your server and manages container deployments, service discovery, and HAProxy configuration.

Prerequisites

  • Linux server
  • Docker installed
  • Sudo access (for system installation)

Automatic Setup

The easiest way to set up a server is using the haloy CLI from your local machine. This command will SSH into your server as root (default), install Docker (if missing), install haloyadm, initialize the daemon, and add the server to your local config.

haloy server setup <server-ip> --api-domain haloy.yourserver.com --acme-email you@email.com

Note: You must have SSH access to the root user on the target server.

This command performs the following steps automatically:

  1. Checks for Docker and installs it if missing
  2. Installs haloyadm on the remote server
  3. Initializes haloyd with your API domain
  4. Retrieves the API token
  5. Adds the server to your local haloy configuration

Once this completes, your server is ready for deployments.

Manual Installation

If you prefer to install manually or cannot use SSH from your local machine, follow these steps.

1. Install haloyadm

SSH into your server and install haloyadm:

curl -fsSL https://sh.haloy.dev/install-haloyadm.sh | sudo sh

2. Initialize haloyd

Standard Setup (Remote Deployment)

For deploying from your local machine to a remote server, initialize with an API domain. This exposes the Haloy API securely via HTTPS:

sudo haloyadm init --api-domain haloy.yourserver.com --acme-email you@email.com

This is required for remote deployments. Without an API domain, the haloy CLI on your local machine cannot communicate with haloyd on the server.

Same-Server Deployment

If you plan to install the haloy CLI directly on the server (alongside haloyd) and only deploy locally, you can initialize without a domain:

sudo haloyadm init

In this setup:

  • Both haloy CLI and haloyd run on the same machine
  • API communication uses localhost
  • No domain is required
  • You’ll add the server as: haloy server add localhost <api-token>

This is useful for:

  • Single-server setups
  • Development environments
  • Situations where a domain isn’t available

Adding a Domain Later

If you initialized without a domain and want to enable remote deployments:

sudo haloyadm api domain haloy.yourserver.com you@email.com

3. Get API Token

Generate an API token to authenticate from your local machine:

sudo haloyadm api token

Save this token securely. You’ll use it to configure your local haloy CLI.

Service Management

Start the Haloy services:

sudo haloyadm start

Stop the services:

sudo haloyadm stop

Restart the services:

sudo haloyadm restart

Development Options

For local development, you can use the local haloyd image:

sudo haloyadm start --dev

Enable debug mode:

sudo haloyadm start --debug

Directory Structure

Haloy uses standard system directories:

System Installation (default):

/etc/haloy/              # Configuration
├── haloyd.yaml          # Haloyd settings
├── .env                 # API tokens

/var/lib/haloy/ # Data
├── haproxy-config/ # HAProxy configs
├── cert-storage/ # SSL certificates
└── db/ # Database files

Uninstalling

Remove Admin Tool Only

curl -sL https://sh.haloy.dev/uninstall-haloyadm.sh | sudo sh

Complete Server Removal

To completely remove Haloy including all data and configurations:

curl -sL https://sh.haloy.dev/uninstall-server.sh | sudo sh

Next Steps