Clusterducks

Installation

Deployment requires at least two components, the control panel and a tunnel service. For running VMs or net-booting bare metal, a third component (storage server) is required. All services may run on a single server or distributed across different points of the Internet.

Containers are useful for development, testing, and quick roll-out of very complicated services. Though any Linux host will work (LXC, virtualization, bare metal) may be used, using the provided Dockerfiles is currently the recommended deployment strategy for self-hosting.

Prerequisites

DNS records for your control panel should be set up before embarking on installation, or SSL certificate verification will not work and the security of your installation may be compromised. Two hosts should be configured:

  • panel.example.com
  • t1.example.com

In a test network, dnsmasq may be used to provide authoritative DNS with just 2 lines added to dnsmasq.conf:

    ```
    address=/panel.example.com/172.17.0.2
    address=/t1.example.com/172.17.0.3
    ```

When using the --dns= switch to docker run, your containers will benefit from this configuration as well.

For all components, starting with a blank MySQL root password is simplest, as the bootstrap scripts will take care of configuring that for you.

To integrate into an existing infrastructure, use /root/mysql.info to provide SQL credentials to the installer in the format:

ROOTPASSWORD="root.password.here.123"
USERPASSWORD="clusterducks.dbuser.password"

Installing the Panel

Docker

  1. Download latest git source

  2. Build the Docker container:

    root@docker-host /usr/share/clusterducks $ docker build -t clusterducks .

  3. Run the panel container, replacing panel1.example.com with your real DNS record that will point to the panel web server (or HA proxy front-end):

    root@docker-host /usr/share/clusterducks $ docker run --name=panel --hostname=panel.example.com clusterducks

Install from source

  1. Configure a basic Ubuntu 14.04 (or higher) VM or LXC - it should be a instance dedicated to the control panel role
  2. Download latest git source to /usr/share/clusterducks or any location that suits your needs
  3. Configure your webserver as desired - apache2 is currently recommended, as we do not provide rewrite rules for other daemons
  4. Install any missing dependencies and correct any permissions errors
  5. Create a cron job that runs panel/cronjob.php as your webserver user every minute with no arguments
  6. Login using installer-provided credentials

Tunnel service

A tunnel is required to broker API requests from the panel to remote storage + compute servers.

The tunnel service is provided by a set of wrappers around OpenSSH to provide secure TCP port forwarding using DB-backed SSH key authentication.

Docker

Docker requires special arguments when running the tunnel service container.

  1. Download the latest tunnel-agent source

  2. Build the Docker container:

    root@docker-host /usr/src/tunnel-agent $ build -t tunnel-agent .

  3. Run the tunnel service, replacing the bold values with your own. If using a local DNS service for testing, use that instead of 8.8.8.8:

    root@docker-host /usr/src/tunnel-agent $ docker run --dns=8.8.8.8 -e PANEL_HOSTNAME=panel.example.com --hostname=t1.example.com -e SERVER_KEY=example.key1 --name=tunnel-service --cap-add net_admin tunnel-agent

Install from source

  1. Configure a basic Ubuntu 14.04 (or higher) VM or LXC - it should be a instance dedicated to the tunnel service role
  2. Download the latest tunnel-agent source to /usr/share/tunnel-agent and cd to the install directory.

  3. Run the install script:

    root@tunnelservice /usr/share/tunnel-agent/install $ chmod +x ./install.sh && ./install.sh -k example.key1 -h panel.example.com

Configuring a Server

Storage nodes may not be containerized due to integration with low-level storage components. A script-based install is the only method.

As of v0.9.2, only /var/www is the supported install prefix for the storage + compute server agent.

  1. Install Debian or Ubuntu;, leave plenty of storage space for a ZFS pool to be created later
  2. Download the latest client source code from Gogs to /var/www and cd to the install directory

  3. Run the installer - replace examplekey.2 with the key created when adding the server in the control panel:

    root@storage /var/www $ chmod +x install.sh && ./install.sh -h panel.example.com -k examplekey.2

  4. Manually create a ZFS pool with the name used in the control panel - this is important.
  5. Re-run the installer and it will create any necessary ZFS filesystems

If you do have any issues, please find us on IRC, #clusterducks@Freenode.