Skip to main content

Running a Utility Cluster on CoreOS

CoreOS is designed to deliver high-density compute resources. The best way to take advantage of this concept on a small scale is run a personal utility cluster (or single machine) to run various utilities like IRC bouncers and the handful of websites that you inevitably end up hosting. CoreOS is a small, efficient operating system, which means you get more bang for your buck even on small cloud instances.

I'm going to walk through setting up ZNC, an IRC bouncer, on a CoreOS cluster. The basic process is to boot a CoreOS server, download a pre-made ZNC container and run the container via systemd.

Booting Your CoreOS Machine(s)

CoreOS runs on most cloud providers — Amazon EC2, Rackspace, Google Compute Engine and more — so pick your favorite and follow the very short setup process. If you have any extra physical servers laying around, CoreOS can also be booted via PXE or virtualized under KVM/QEMU, VMware and more.

Login to the Machine

You must login to a CoreOS machine with SSH keys — passwords are not supported at all. We're only supporting good habits! To connect run:

ssh core@your_ip_address

Set up the ZNC Container

Let's pull down the container onto the CoreOS machine. It's worth noting that docker will do this for you if it can't find the image locally, but we're including it explicitly so you can understand what's going on.

docker pull coreos/znc

Now we need to run through the intial set up process provided by ZNC. To do this, we need to run a bash prompt inside the container:

docker run -t -i coreos/znc /bin/bash

After the container starts, we need to run the setup command. Since ZNC doesn't allow you to run it as root, we need to specify a different user (irc)to run the command with su:

su - irc -c 'znc --makeconf'

Follow the steps when prompted to completely set up ZNC. I suggest listening on port 6000, don't use SSL and enabling all of the default modules. Refer to ZNC's configuration guide if you run into any issues. When it completes, we need to exit to stop the container so we can commit our changes.

Commit the Container Changes

Grab the container ID from docker ps -a (at the top of the list) and insert it into:

docker commit container_id yourusername/znc

You're customized ZNC container is now saved locally on your CoreOS machine. Now we need to run it. This time we need to forward the port you selected into the container. In my examples I'll be using 6000. Instead of starting ZNC from our bash prompt, we can start it directly by telling docker to run ZNC in the foreground. Running in the foreground is important because our container will stop running when the command it runs is completed.

docker run -d -p 6000:6000 yourusername/znc su - irc -c 'znc --foreground'

Connect via IRC Client

Connect to your ZNC server by using the public IP address, port and other configuration options you set up. You may have to debug as necessary.

Write the Unit File

CoreOS uses systemd to manage containers that get run by the operating system. For your ZNC container to restart after an automatic update, we need to write a unit file to manage it. These files are pretty straightforward and you can read about more complex examples in our Getting Started with systemd guide.

[Unit]
Description=ZNC IRC Service
After=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker run --rm -p 6000:6000 yourusername/znc su - znc -c 'znc --foreground'

[Install]
WantedBy=local.target

The --rm flag will remove old copies of this container when they stop. This prevents the disk from filling up with containers that we don't want to ever run again.

Next Steps

You should now have a fully set up utility cluster (or server) running a single container. Next steps would include setting up a simple static site hosted within a container or construct your own container that runs another utility. Check out our guides for Getting Started with docker and Getting Started with etcd.