_   _   _
 / \ / \ / \
( H | O | I )
 \_/ \_/ \_/

---- Bare Metal PaaS


Synopsis
--------
Hoi is a host management program that orchestrates other services, so projects
can be hosted with the execution of just one command. It automates setting up
several aspects of a project i.e. SSL certificates, databases, cron jobs and
HTTP auth for staging areas.

Aspects of a project are defined by the Hoifile, a short and sweet per project
configuration file.

In architecting hoi we made sure to stay very pragmatic, thus hoi uses a
pre-defined set of established/no-nonsense technologies.

-- Hoi is currently in development and until it reaches 1.0, it --
-- should be considered not ready for general production use.   --

Reasoning
---------
Hoi has been created to ease hosting of the growing number of Atelier Disko
client projects. By minimizing project setup costs, we wanted to enable us
to conduct quick experiments.

"It's as complicated as you want it to be." [0]

Atelier Disko isn't primarly an infrastructure company, so we don't like to
afford maintaining too ambitious solutions. Resources freed from deliberately
choosing a classic shared hosting architechture are re-invested into providing
a stable, secure and performant hosting environment with good resource
utilization.

Our projects are primarly PHP-based web applications. They are distinct in what
they do but pretty uniform in how the are structured and in the technology they
need.

[0] https://twitter.com/alexander_h/status/751470506503798784

Is it for you?
--------------
If your hosting needs are similar and are ready to sacrifice the benefits of
i.e. containers for ease of use or you are running services that are not well
suited for per-project containers (i.e. PHP FPM or MySQL), hoi might also be
something for you.

What's inside?
--------------
Hoi consist of a server (hoid) backend and client (hoictl) to control the
server. It features several modules ("runners") which take care of the needs
of a project.

- "web"
  Serves the project under given domains, taking care of SSL
  certificates and basic auth where needed.
  https://godoc.org/github.com/atelierdisko/hoi/runner#WebRunner

- "php"
  Safely enables per project PHP(1) settings.
  https://godoc.org/github.com/atelierdisko/hoi/runner#PHPRunner

- "cron"
  Starts cron jobs while reducing resource congestion.
  https://godoc.org/github.com/atelierdisko/hoi/runner#CronRunner

- "worker"
  Manages long running worker processes with resource controls.
  https://godoc.org/github.com/atelierdisko/hoi/runner#WorkerRunner

- "db"
  Creates databases and users with minimum set of privileges.
  https://godoc.org/github.com/atelierdisko/hoi/runner#DBRunner

- "volume"
  Mounts persistent and/or temporary volumes into the project.
  https://godoc.org/github.com/atelierdisko/hoi/runner#VolumeRunner


Installation
============
The following handful of commands will install hoi into your system:

$ go get github.com/atelierdisko/hoi
$ cd $GOPATH/src/github.com/atelierdisko/hoi
$ PREFIX= make install
$ cp conf/hoid.service /etc/systemd/system/
$ systemctl enable --now hoid


Project Configuration: The Hoifile
==================================
https://godoc.org/github.com/atelierdisko/hoi/project#Config

The Hoifile defines the needs of a project and provides a minimum
set of configuration. The remaining configuration is discovered
automatically once the project is loaded.

It uses a directive based configuration syntax similar to the NGINX
configuration files.

A minimal Hoifile has 3 lines:
  name = "example"
  context = "prod"
  domain example.org {}

A more advanced Hoifile might look like this:
  name = "example"
  context = "prod"
  domain example.org {
    SSL = {
      certificate = "config/ssl/example.org.crt"
      certificateKey = "config/ssl/example.org.key"
    }
    aliases = ["example.com", "example.net"]
  }
  database example {
    password = "s3cret"
  }
  cron reporter {
    schedule = "daily"
    command = "bin/compile-report"
  }
  worker media-processor {
    instances = 2
    command = "bin/process-media"
  }
  volume media_versions {}
  volume tmp {
	isTemporary = true
  }

Once a project contains a Hoifile, it's loaded with a single command:
$ cd /var/www/foo
$ hoictl load

The loaded configuration can be further manipulated i.e. by adding an
alias to a domain:
$ hoictl domain example.org --alias=example.com


Server Configuration: hoid.conf
===============================
https://godoc.org/github.com/atelierdisko/hoi/server#Config

Customizing Service Templates
-----------------------------
The templates used by hoid to generate service configuration can be customized,
they reside inside conf/templates and use Go Template[0] syntax.

[0] https://golang.org/pkg/text/template/


Copyright & License
===================
Hoi is Copyright (c) 2016 Atelier Disko if not otherwise
stated. Use of the source code is governed by a BSD-style
license that can be found in the LICENSE file.


Versions & Requirements
=======================
The Go language >= 1.5 is required to build the project.
 Must have go vendor support enabled.

Hoi is continously tested on Linux and Darwin.

The web runner requires nginx(8) and openssl(1)
  The default template for NGINX will log to syslog/journald. This feature is
  available in NGINX >= 1.7.1. To lower this version requirement the "useLegacy"
  option can be enabled (which will log to STDERR instead).

The cron and worker runners require systemd(1)
  Recent systemd versions are always supported, older ones (i.e. 215) are
  probably supported via the "useLegacy" option.

The PHP runner requires php-fpm(8)
  If you don't enable this runner you can drop this requirement.

The DB runner requires mysqld(8) or MariaDB
  If you don't enable this runner you can drop this requirement. MySQL >= 5.7.6
  or MariaDB >= 10.1.3 are required to use more efficient queries. By enabling
  "useLegacy" older versions may be used.


Development
===========
Hoi comes with unit tests which can be safely executed as they don't
touch the system itself. The unit tests can be run via:

$ make unit-tests

Not everything is - yet - covered by unit tests. To conduct system tests
this project comes with a Vagrantfile to boot up a VM. The system tests
should only ever be run inside a VM as they modify the systen they run on.

HOST  $ go get github.com/atelierdisko/hoi
HOST  $ cd $GOPATH/src/github.com/atelierdisko/hoi
HOST  $ vagrant up
HOST  $ vagrant ssh

GUEST $ cd go/src/github.com/atelierdisko/hoi
GUEST $ sudo -i
GUEST $ make system-tests
GUEST $ systemctl start hoid
GUEST $ hoictl --project=/var/www/example load