SebastianWendel / srx-platform-nix

srx.digital - nix platform repository. Mirror of https://code.srx.digital/srx/srx-platform-nix/

srx digital - nix platform repository

This is the platform repository of srx.digital, a Nix development and operations company based in Hamburg, Germany.

NixOS is a Linux distribution built on the Nix package manager, utilizing declarative configuration to ensure reproducible and reliable system setups.

This repository contains opinionated configurations for deploying NixOS systems and cloud infrastructures with Terraform, written in pure Nix expressions. It offers developers and DevOps engineers an insight into the potential of Nix.

📜 Principles of Operation

This repository uses 100% Infrastructure as Code and does not need to be configured manually. All services are monitored and backed up. Common services are modularized for reuse, but the separation of custom configurations is in progress. Reusable components will be moved to a separate Flake module in the near future.

📌 Note

Some customer-specific configurations are stored in a private Git repository and imported as the srx-nixos-shadow flake to protect customer infrastructure. Due to its private nature, some tasks may fail and should be commented out. Generally, all expressions should evaluate without issues.

🛠️ Components

• flake-parts: Simplify Nix Flakes with the module system.
• git-hooks: Seamless integration of git hooks with Nix.
• agenix: Encrypted secrets for NixOS and Home Manager.
• deploy-rs: A multi-profile Nix-flake deployment tool.
• nixos-anywhere: Install NixOS anywhere via SSH.
• disko: Declarative disk partitioning.
• srvos: NixOS profiles for servers.
• Tang & Clevis: An automated encryption framework for full disk encryption.
• Lanzaboote: Secure Boot for NixOS.
• home-manager: Manage user environments using Nix.
• terranix: Create OpenTofu JSON files the NixOS way.
• kubenix: Kubernetes management with Nix.
• stylix: Apply consistent color schemes, fonts, and wallpapers.
• hydra: The Nix-based continuous build system.

📁 Repository layout

├── hosts         - NixOS server configurations
├── lib           - Reusable Nix libraries
├── modules       - Reusable NixOS modules
├── nix           - Flake-parts modules
├── overlays      - Nix package overlays
├── secrets.nix   - Age-encrypted secrets
├── terranix      - Terraform Nix expressions
├── default.nix   - Legacy support with flake-compat
├── flake.lock    - Lock file for version pinning
└── flake.nix     - Flakes configuration

🚀 Getting started

📋 Prerequisites

Before proceeding, ensure the following tools are installed:

• Git: For cloning and managing the repository.
• direnv: To automatically enter Nix environments.
• Nix package manager: Essential for Nix or NixOS operations.

🛠️ Commands

Run menu or nix flake show to view all commands and aliases provided by the devshell, as defined in nix/devshell.nix.

🖥️ NixOS

🔐 Secrets

Secrets are encrypted using agenix. To add secret files and new hosts with their SSH public key, edit nix/hosts.nix.

• agenix --edit edits FILE using $EDITOR
• agenix --decrypt decrypts FILE to STDOUT
• agenix --rekey re-encrypts all secrets with specified recipients

🏭 Development

To begin, run nix develop in the source tree to enter the development shell, or use direnv for automatic entry. Check flake.nix or run nix flake show to view the flake definition. Server definitions are described in the hosts folder. Module definitions are located in the nix/modules.nix and modules folders.

🧪 local Testing

To build and run a local QEMU VM, use the following steps:

1. Build the system with:

   nixos-rebuild build-vm --flake .#dev-vm

2. Configure the network settings:

   export QEMU_NET_OPTS="hostfwd=tcp::2221-:22"

3. Start the VM:

   result/bin/run-dev-vm-vm

4. Access the VM via SSH:

   ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@localhost -p 2221

🎯 Deployment

deploy-rs is a straightforward deployment tool for NixOS systems. It is configured in nix/deploy.nix, where you can adjust autoRollback or magicRollback options.

To deploy, run:

deploy .#dev-vm

For more information on usage, refer to the deploy --help documentation.

🪐 Terraform

This project uses OpenTofu and terranix for creating Terraform JSON files the Nix way.

🔗 Environment Variables

Create a local and private .envrc.local file to authenticate with remote services during local development and operations.

• AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: Required for accessing S3 services, crucial for state management. Refer to Terraform S3 State for more details.
• GITHUB_TOKEN: Authenticates against GitHub for repository access and API interactions. Details.
• HYDRA_HOST, HYDRA_USERNAME, HYDRA_PASSWORD: Configures and authenticates with a Hydra server for CI/CD operations. Hydra provider documentation.
• GRAFANA_AUTH: Enables Grafana server authentication for dashboard access and API use. Grafana provider usage.
• MINIO_ENABLE_HTTPS, MINIO_ENDPOINT, MINIO_ROOT_USER, MINIO_ROOT_PASSWORD: Sets up MinIO services, ensuring secure and authenticated connections. MinIO provider usage.

📦 State Management

The Terraform state is stored outside the repository in an S3 Bucket, configured in terraform.nix and hosted by minio.nix.

🔧 Configuration

Terraform version and providers are pinned and configured in nix/terranix.nix. Terraform resources are declared in the terranix folder.

🕹️ Terraform Commands

• nix run .#tf-init - Initializes the working directory.
• nix run .#tf-state - Performs basic state modifications.
• nix run .#tf-import - Import existing infrastructure resources.
• nix run .#tf-validate - Validates using tfsec, configured in tfsec.nix.
• nix run .#tf-plan - Creates the execution plan.
• nix run .#tf-apply - Executes the actions proposed in the plan.
• nix run .#tf-destroy - Destroys all remote objects.

🧰 Helpers

• nix run .#tf2nix resource.tf - Converts HCL files to Nix.
• nix run .#json2nix resource.yaml - Converts JSON or YAML files to Nix.

🧩 Common Functions

Generalized functions for reuse are in lib/terraform.nix and nix/terranix.nix.

🔄 Updates

This project uses nix flakes to manage nixpkgs versions. To upgrade, use nix flake update for all inputs or nix flake update nixpkgs to update a single flake input.

To check if a remote system is behind your flake state, run nix run .#nix-upgrades:

🔍 Scanning for upgradable hosts...

dev-vm: ⚠️ Modified: 24.05.20240618.938aa15

🤖 CI/CD

I utilize the Nix Hydra project to test and build all packages and hosts, strictly following the Zero Hydra Failures paradigm to ensure every build is successful and stable.

You can view all our jobs and their statuses at build.nix.srx.digital.

🚧 Reporting issues

If you experience any issues with the infrastructure, please post a new issue to this repository.

💬 Contact

Need help with Nix? Write me an e-mail to book an appointment for Nix/NixOS/DevOps related topics. You can find me at:

• SRX Digital - Development & Operations
• Nix Hamburg Matrix channel for live discussions.

📚 Links

• Nix packages search
• NixOS options search
• Nix Manual
• NixOS Manual
• NixOS & Flakes Book
• NixOS Wiki
• Awesome Nix

📜 License

All files in this repository are licensed under the terms of the MIT License (MIT). Please refer to the full license text in LICENSE.