Installation¶

Gradient is distributed as a NixOS module. The recommended way to install it is via the Nix flake.

Prerequisites¶

• NixOS with flakes enabled
• PostgreSQL 18 or newer (can be configured automatically); the server refuses to start against older versions
• An NGINX reverse proxy (can be configured automatically)

Adding Gradient to Your Flake¶

Add Gradient as a flake input and apply the overlay:

{
  inputs.gradient.url = "github:wavelens/gradient";
  # Optional: pin nixpkgs to match Gradient's
  # inputs.gradient.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { self, nixpkgs, gradient, ... }:
  let
    pkgs = import nixpkgs {
      system = "x86_64-linux";
      overlays = [ gradient.overlays.default ];
    };
  in {
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        gradient.nixosModules.default
      ];
    };
  };
}

Minimal NixOS Configuration¶

In your configuration.nix:

{
  services.gradient = {
    enable        = true;
    frontend.enable = true;
    domain        = "gradient.example.com";

    # Secrets - we recommend sops-nix or agenix
    cryptSecretFile = "/var/lib/gradient/crypt-secret"; # base64-encoded password
    jwtSecretFile   = "/var/lib/gradient/jwt-secret";   # random alphanumeric RS256 secret

    # Convenience options
    configurePostgres         = true;
    reverseProxy.nginx.enable = true;
  };
}

The server does not start a worker automatically. Add a co-located worker to handle jobs on the same machine (import the gradient-worker module and set services.gradient.worker.enable = true), or deploy gradient-worker on separate build machines. See Configuration → Workers for the full setup.

All available options are searchable at the Options Search.

TLS configuration¶

Two independent settings control TLS, and conflating them is a common source of broken logins:

• services.gradient.useTls (default true) controls how Gradient itself behaves: it emits https:// URLs (the OIDC redirect URL, GRADIENT_SERVE_URL) and marks session cookies Secure. Set it to false only for a genuinely plaintext-HTTP deployment - turning it off so that nginx stops managing certificates will also stop your browser from sending the secure session cookie, breaking login.
• services.gradient.reverseProxy.nginx.manageTls (default true) controls whether nginx obtains and serves the certificate itself (it sets the vhost's enableACME and forceSSL). It has no effect when useTls = false.

If TLS is terminated by an upstream proxy (Traefik, Cloudflare, a load balancer) that forwards plain HTTP to nginx, keep useTls = true so Gradient still emits https:// URLs and secure cookies, and set manageTls = false so nginx doesn't also try to obtain a certificate:

{
  services.gradient = {
    useTls = true;                          # emit https URLs + secure cookies
    reverseProxy.nginx.enable = true;       # still let nginx serve static files
    reverseProxy.nginx.manageTls = false;   # upstream proxy terminates TLS
  };
}

Binary Cache (Optional)¶

Add the public cache to avoid rebuilding Gradient from source:

{
  nix.settings = {
    substituters     = [ "https://public.gradient.ci/cache/main" ];
    trusted-public-keys = [
      "public.gradient.ci-main:qmxRE+saUvhNa3jqaCMWje+feVU77TjABchZrPGf7A8="
    ];
  };
}

Applying the Configuration¶

sudo nixos-rebuild switch --flake .#yourhostname

Gradient will start automatically and be available at https://gradient.example.com.

First Steps After Installation¶

1. Navigate to https://gradient.example.com/account/register to create the first user account.
2. Log in and create an organization.
3. Create a Nix cache (optional - required for binary cache serving).
4. Create your first project pointing to a Git repository.
5. Trigger an evaluation - a connected gradient-worker will fetch, evaluate, and build.