nix-oci-lock

Status: ALPHA

This generates lockfiles for your virtualisation.oci-containers.containers.

Example

{
  programs.nix-oci-lock = {
    enable = true;
    lockFile = ./oci-lock.json;
  };

  virtualisation.oci-containers.containers = {
    app-db = {
      image = "postgres:latest";
      environment = {
        POSTGRES_USER = "postgres";
        POSTGRES_PASSWORD = "changeme";
        POSTGRES_DB = "app";
      };
      volumes = [ "app-db-data:/var/lib/postgresql" ];
    };
    app-redis.image = "valkey/valkey:latest";
  };
}

Usage

Currently, only flakes are supported. Get started by importing this flake’s NixOS module, e.g.:

{
  inputs.nix-oci-lock.url = "https://git.bartoostveen.nl/bart/nix-oci-lock.git";
  outputs = { nixpkgs, ... }@inputs: {
    nixosConfigurations.foo = nixpkgs.lib.nixosConfiguration {
      modules = [ inputs.nix-oci-lock.nixosModules.default ];
    };
  };
}

See examples for examples.

Roadmap

Non-flake NixOS configurations
Substituting password files for OCI login, possibly using sops-nix/agenix
Signature verification
Keeping track of timestamps
Proper tests
Proper docs
Proper exit codes
CI
CTRL+C handler that writes old lock file

Reference

All docs are available at https://nix-oci-lock.bartoostveen.nl/ (unstable). NixOS options reference is rendered at https://nix-oci-lock.bartoostveen.nl/options.html (unstable).

License

This project is licensed under the GNU General Public License version 3. You can find a copy here.

Commands

nix-oci-lock

OCI digest lock manager for NixOS

Synopsis

nix-oci-lock manages your virtualisation.oci-containers.containers images by generating lockfiles. This CLI helps you to update said lockfile.

Options

      --flake string   flake URI or path to evaluate (default ".")
  -h, --help           help for nix-oci-lock
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock check

Check for stale OCI image locks

Synopsis

Check whether OCI image tags have changed since the current lock file was generated.

nix-oci-lock check [flags]

Options

  -h, --help   help for check

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock completion

Generate the autocompletion script for the specified shell

Synopsis

Generate the autocompletion script for nix-oci-lock for the specified shell. See each sub-command’s help for details on how to use the generated script.

Options

  -h, --help   help for completion

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock completion bash

Generate the autocompletion script for bash

Synopsis

Generate the autocompletion script for the bash shell.

This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.

To load completions in your current shell session:

source <(nix-oci-lock completion bash)

To load completions for every new session, execute once:

Linux:

nix-oci-lock completion bash > /etc/bash_completion.d/nix-oci-lock

macOS:

nix-oci-lock completion bash > $(brew --prefix)/etc/bash_completion.d/nix-oci-lock

You will need to start a new shell for this setup to take effect.

nix-oci-lock completion bash

Options

  -h, --help              help for bash
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock completion fish

Generate the autocompletion script for fish

Synopsis

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

nix-oci-lock completion fish | source

To load completions for every new session, execute once:

nix-oci-lock completion fish > ~/.config/fish/completions/nix-oci-lock.fish

You will need to start a new shell for this setup to take effect.

nix-oci-lock completion fish [flags]

Options

  -h, --help              help for fish
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock completion powershell

Generate the autocompletion script for powershell

Synopsis

Generate the autocompletion script for powershell.

To load completions in your current shell session:

nix-oci-lock completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

nix-oci-lock completion powershell [flags]

Options

  -h, --help              help for powershell
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock completion zsh

Generate the autocompletion script for zsh

Synopsis

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(nix-oci-lock completion zsh)

To load completions for every new session, execute once:

Linux:

nix-oci-lock completion zsh > "${fpath[1]}/_nix-oci-lock"

macOS:

nix-oci-lock completion zsh > $(brew --prefix)/share/zsh/site-functions/_nix-oci-lock

You will need to start a new shell for this setup to take effect.

nix-oci-lock completion zsh [flags]

Options

  -h, --help              help for zsh
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock info

Show OCI lock information

Synopsis

Display declared image references, resolved digests, and lock metadata for evaluated containers.

nix-oci-lock info [node] [container] [flags]

Examples

nix-oci-lock info
nix-oci-lock info server
nix-oci-lock info server immich

Options

  -h, --help   help for info

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock sync

Sync with remote

Synopsis

Get data from specified remote Docker daemon and sync the lockfile with the current host’s state

nix-oci-lock sync [flags]

Options

      --commit               whether to commit to git
      --docker-host string   connection string for the Docker socket (default "unix:///var/run/podman.sock")
  -h, --help                 help for sync

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

nix-oci-lock update

resolve and update OCI image digests

Synopsis

Update OCI image digests for all or one NixOS configuration(s), for either all containers, or a single container in particular.

nix-oci-lock update [node] [container] [flags]

Examples

nix-oci-lock update
nix-oci-lock update server
nix-oci-lock update server immich

Options

      --commit   commit the lock file changes immediately with an appropriate commit message
      --dry      show what an update run would do, do not write the lock file (mutually exclusive with --commit)
  -h, --help     help for update

Options inherited from parent commands

      --flake string   flake URI or path to evaluate (default ".")
      --lock string    path to OCI lock file (default "oci-lock.json")

Options

programs.nix-oci-lock.enable

Whether to enable nix-oci-lock.

Type: boolean

Default:

false

Example:

true

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

programs.nix-oci-lock.package

The nix-oci-lock package to use.

Type: package

Default:

pkgs.nix-oci-lock

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

programs.nix-oci-lock.hostName

The hostname to use from the lockfile

Type: string

Default:

"nixos"

Example:

"foo-server"

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

programs.nix-oci-lock.lockFile

Path to the lockfile nix-oci-lock should override your system config with

Type: absolute path

Example:

"./oci-lock.json"

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

programs.nix-oci-lock.lockedContainers

Additional container locks to import, must be of the same format as the lock file

Type: attribute set of (submodule)

Default:

{ }

Example:

{
  bar = {
    containers = {
      postgres = {
        locked = "docker.io/library/postgres:latest@sha256:8ff36f3c66371cba71d20ceedccfc3de9669a68737607888c4ef0af93abe8e39";
        original = "postgres:latest";
      };
    };
  };
  foo = {
    containers = {
      valkey = {
        locked = "docker.io/valkey/valkey:latest@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9";
        original = "valkey:valkey/latest";
      };
    };
  };
}

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

programs.nix-oci-lock.lockedContainers.<name>.containers

Locked containers for this host

Type: attribute set of (submodule)

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

programs.nix-oci-lock.lockedContainers.<name>.containers.<name>.locked

The full locked container reference

Type: string

Example:

"docker.io/valkey/valkey:latest@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9"

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

programs.nix-oci-lock.lockedContainers.<name>.containers.<name>.original

The original container image, will be used for checks in the future.

Type: string

Example:

"valkey:valkey/latest"

Declared by:

/nix/store/vj1gxcxcpa5ngvxr3by4dmcz5hbf6rmm-source/module.nix

Keyboard shortcuts

nix-oci-lock documentation