Skip to content

deployment.md

Latest commit

 

History

History
161 lines (116 loc) · 3.42 KB

deployment.md

File metadata and controls

161 lines (116 loc) · 3.42 KB

deployment — Declarative deploy-rs DSL

This module provides a declarative interface for defining deploy-rs nodes directly inside host files.
It replaces the traditional deploy-rs configuration with a cleaner, per-host DSL that integrates automatically into the flake.

Purpose

  • Allow each host to declare its own deployment targets
  • Avoid editing flake.nix when adding new servers
  • Support multiple deployment profiles per host
  • Provide a consistent structure for remote activation

The flake collects all deployment definitions and generates:

deploy.nodes {...}

This enables multi-node deployments from a single flake.

Structure

A deployment entry has the following shape:

deployment.<node> = {
  hostname = "example.com";
  fastConnection = false;

  profiles.system = {
    sshUser = "admin";
    user = "root";
    path = deploy-rs.lib.x86_64-linux.activate.nixos self.nixosConfigurations.<host>;
  };
};

Where

  • <node> is the name used by deploy-rs
  • <host> is the NixOS configuration to deploy

Options

deployment.<node>.hostname

Remote host address or IP.

deployment.<node>.fastConnection

Optimizes SSH settings for low-latency connections. Defaults to false.

deployment.<node>.profiles.<name>.sshUser

User used for SSH connection.

deployment.<node>.profiles.<name>.user

User used for activation on the remote machine.

deployment.<node>.profiles.<name>.path

Activation package generated by deploy-rs.

This is typically:

deploy-rs.lib.${system}.activate.nixos self.nixosConfigurations.<host>

How the flake processes deployments

  1. Each host may define zero or more deployment.<node> entries.
  2. The flake collects all of them.
  3. The structure is flattened.
  4. The result becomes:
deploy.nodes = {
  <node1> = { ... };
  <node2> = { ... };
  ...
};

This means:

  • You can deploy any host without editing the flake.
  • Multiple hosts can define multiple nodes.
  • Nodes can have multiple profiles.

Examples

minimal deployment

{pkgs, ...}: { 
  # ... other host configurations ... 
  deployment.myServer = {
    hostname = "0.0.0.0";
    profiles.system = {
      sshUser = "admin";
      user = "root";
      path = deploy-rs.lib.x86_64-linux.activate.nixos self.nixosConfigurations.myServer;
    };
  };
  # ... other host configurations ...
}

multiple profiles

{pkgs, ...}: {
  # ... other host configurations ...
  deployment.edge = {
    hostname = "edge.example.com";

    profiles.system = {
      sshUser = "admin";
      user = "root";
      path = deploy-rs.lib.x86_64-linux.activate.nixos self.nixosConfigurations.edge;
    };

    profiles.backup = {
      sshUser = "backup";
      user = "root";
      path = deploy-rs.lib.x86_64-linux.activate.nixos self.nixosConfigurations.edge;
    };
  };
  # ... other host configurations ...
}

Relationship with migration scripts

The deploy-migration.sh script relies on this module:

  • It reads deploy.nodes.<node>.hostname
  • It reads deploy.nodes.<node>.profiles.system.sshUser
  • It reads the activation path
  • This module is therefore required for:
  • deploy-migration
  • remote PostgreSQL-safe deployments

When to use this module

Use it when:

  • A host needs remote deployment
  • You want declarative deploy-rs configuration
  • You want to avoid editing the flake

Do not use it for:

  • local rebuilds
  • non-NixOS targets
  • ad-hoc SSH commands