Skip to content

Run a spindle

A spindle runs CI pipelines for your repositories. You do not need your own spindle to use CI. Run one if you want CI on your own machines, or secrets that stay on them.

Before you start

Section titled “Before you start”

You need:

  • A Linux machine with KVM that stays online.
  • A DNS name for the spindle, for example spindle.example.com. Choose a name that you will keep, because the spindle uses it as its identity.
  • Your DID. If you do not know it, look up your handle at pds.ls.
  • A reverse proxy, for example Caddy, to give the spindle TLS.

Make a signing key:

openssl ecparam -name prime256v1 -genkey -noout -out /var/lib/secrets/spindle-key.pem
chmod 600 /var/lib/secrets/spindle-key.pem

Run on NixOS

Section titled “Run on NixOS”

Add the Tangled flake and enable the spindle module:

{
  imports = [ tangled.nixosModules.spindle ];


  services.tangled.spindle = {
    enable = true;
    server = {
      hostname = "spindle.example.com";
      owner = "did:plc:yourdid";
    };
    keyPath = "/var/lib/secrets/spindle-key.pem";
    contact.email = "admin@spindle.example.com";
    artifactStores.s3.bucket = "";
  };


  systemd.tmpfiles.rules = [
    "L+ /var/lib/spindle/images/nixos - - - - ${tangled.packages.x86_64-linux.spindle-nixos-image}"
  ];
}

The spindle listens on port 6555. Point your reverse proxy at it. The proxy must also pass websocket upgrades and send CORS headers.

Let people use it

Section titled “Let people use it”

At first, the spindle runs CI only for you. To let another person use it, run this on the spindle machine:

spindle allowlist add friend.example.com

Check that it works

Section titled “Check that it works”
curl https://spindle.example.com/_health

Then, in the Tangled web app, open a repository’s Settings → Pipelines and select your spindle. Push a workflow to start a run.

Self-hosting explains how a spindle runs and how to configure it. Spindle Configuration lists all settings.