# Run a spindle

> Run a spindle, the server that runs CI for your repositories.

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

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](https://pds.ls).
* A reverse proxy, for example Caddy, to give the spindle TLS.

Make a signing key:

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

> **Caution**
>
> Keep a backup copy of the signing key. If you lose it, other services stop trusting the spindle for some time.

## Run on NixOS

Add the Tangled flake and enable the `spindle` module:

```nix
{
  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

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

```sh
spindle allowlist add friend.example.com
```

## Check that it works

```sh
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](/docs/spindles/writing-workflows/) to start a run.

[Self-hosting](/docs/spindles/self-hosting/) explains how a spindle runs and how to configure it. [Spindle Configuration](/docs/reference/spindle-config/) lists all settings.