Running Heim without Docker

On resource-constrained systems, the memory or disk cost of employing Docker may outweigh the convenience of the technology. This guide collects know-how gathered from the Dockerfiles and personal experience on how to run Heim outside its containers.

Prerequisites

Heim requires the following software:

• A compiler for the Go programming language for building the backend.
• The PostgreSQL database for running the backend.
• The Node.js runtime for building the frontend.
• Git is used by the frontend build.

The sql-migrate tool is installed in Step 3.

Auxiliary software

The following tools are employed by Euphoria in addition:

• etcd may be used to coordinate multiple backends.
• HAProxy as a reverse proxy for multiple backends.
• The Sentry error reporting platform is used by the frontend.

Setup

1. Install the prerequisites.

2. Create a separate user account for privilege separation. This step may be omitted; in that case, further steps may have to be modified accordingly. We call the user heim, and locate its home directory in /var/lib/heim (henceforth $HOME). From a privileged shell, run

   adduser --system --group --shell /bin/sh --home /var/lib/heim heim
   

   For the following steps, from a shell of the heim user implies that the current directory is $HOME.

3. Install the sql-migrate tool. From a shell of the heim user, run

   go get -v github.com/rubenv/sql-migrate/...
   

   This puts the executable into the $HOME/go/bin directory. For the following steps, ensure that it is in heim's $PATH.

4. Check out the repository. From a shell of the heim user, run

   git clone https://github.com/euphoria-io/heim
   

   (to check the repository out into $HOME/heim). In the repository, run

   git submodule update --init
   

   (to fetch the dependency repository).

5. Create the database and its (DB) user. We call the database (imaginatively) heim, and its user heim as well (remark that the database user is generally separate from the OS user; however, PostgreSQL requires their names to match as a security feature); we use heimlich as a password for the user (you might wish to use another). From a shell of the database service account, perhaps postgres, run

   createuser -P heim
   createdb -O heim heim
   

6. Migrate the database. From a shell of the heim user, enter the following data into a text file at dbconfig.yml:

   development:
     dialect: postgres
     datasource: dbname=heim user=heim password=heimlich sslmode=disable
     dir: heim/backend/psql/migrations
   

   (you might wish to set restrictive file permissions because it includes the database password), and run

   sql-migrate up
   

7. Wire up the directory structure. From a shell of the heim user, run

   mkdir -p go/src/euphoria.io
   ln -s $HOME/heim go/src/euphoria.io
   ln -s $HOME/heim/_deps/node_modules heim/client
   

   For the following steps, ensure that $GOPATH includes $HOME/go and $HOME/heim/_deps/godeps (in that order), and that $PATH includes $HOME/heim/client/node_modules/.bin.

8. Build the backend. From a shell of the heim user, run

   go install -ldflags \
     "-X main.version=$(git --git-dir heim/.git rev-parse HEAD)" \
     euphoria.io/heim/heimctl
   

   (where the nested git command obtains the hash of the current commit; you can also substitute it manually, or use some arbitrary value, although the latter is not tested).

   Note: Depending on the Go version (or other factors), the build might fail, complaining about missing standard packages (in my case, golang.org/x/sys/unix); obtaining those using go get explicitly might work around the issue.

9. Build the frontend. From a shell of the heim user, run

   cd heim/client
   NODE_ENV=... HEIM_ORIGIN=... EMBED_ORIGIN=...
   export NODE_ENV HEIM_ORIGIN EMBED_ORIGIN
   gulp build
   

   substituting appropriate values for the variables, where:

   • NODE_ENV is one of development or production,
   • HEIM_ORIGIN is the origin the Heim instance will serve (e.g. https://euphoria.io),
   • HEIM_PREFIX (optional) is the path prefix for the frontend (e.g. /dev/chromakode, or the empty string),
   • EMBED_ORIGIN is the origin where embeds will be served from (e.g. https://embed.space),
   • SENTRY_ENDPOINT (optional) is where the error reporter will send to (consult your Sentry instance for more information, or enter an empty string to disable error reporting).

   Note: This step can be particularly resource-intensive, regardless of Docker. The vanilla frontend's build process depends on old Node.js functionality and might not work on newer systems; the Dockerfiles use Ubuntu 14.04 Trusty Tahr.

10. Prepare the Heim configuration. Create a copy of the heim.yml file from the source repository by running from a shell of the heim user:

    cp heim/heim.yml heim.yml
    

    and edit it to have the following contents:

    cluster:
      etcd-host: mock
      server-id: test
    database:
      dsn: postgres://heim:heimlich@localhost/heim?sslmode=disable
    email:
      server: $stdout
    kms:
      aes256:
        key-file: /var/lib/heim/heim/backend/console/keys/masterkey
    
    set_insecure_cookies: false  # As necessary.
    allow_room_creation: false  # As necessary.
    

    (You might wish to set restrictive file permissions because it includes the database password.)

11. Start the servers. From a shell of the heim user, run the Heim backend:

    heimctl -config heim.yml serve -static heim/client/build/heim \
      -email-templates heim/client/build/email -http $HEIM_PORT
    

    From another shell of the heim user, run the embed server:

    heimctl serve-embed -static heim/client/build/embed \
      -http $EMBED_PORT
    

    In both cases, substitute appropriate values for the *_PORT variables.