Installing the Developer Environment

Objective

Configure a git repository in your organization to use the Panfactum devenv which includes all the necessary tooling to launch and work with the stack.

Install Prerequisite Tooling

Follow this guide section to install a few prerequisite tools.

Choosing a Repository

In the Panfactum stack, everything required to set up your developer environments and live infrastructure is defined in code.

As you begin, you must choose a repository where you want this code to live.

We strongly recommend a monorepo setup where all application, tooling, and infrastructure code gets versioned together. 1 However, if you already have many repositories, we recommend setting up a dedicated "stack" repository where this code can live.

This repository will contain the following pieces of functionality:

Much (if not all) of your infrastructure-as-code (OpenTofu / Terraform)
All of your configuration-as-code (Terragrunt) for every live environment
All of your deployment pipelines
All of your local developer tooling
All of your immediate integration tooling for local development

We provide a reference repository setup that you can benchmark against as you progress through the setup documentation.

Integrate the Panfactum devenv

Two fundamental tools codify your local developer environment:

nix: A package manager and programming language that works on all operating systems
devenv: A set of utilities built upon nix for creating developer environments

We provide a foundational devenv that automatically installs all tooling that you need to work on the Panfactum stack. These tools are versioned in tandem with the live infrastructure to ensure compatibility. They are installed in an isolated directory that won't interfere with other tooling on your local system.

The following steps will integrate the Panfactum tooling into your repository:

Create a devenv.nix file in the root of your repo. We recommend starting with the below template and expanding it as needed. You can read more about the available syntax and options for devenv here. We also provide a dedicated guide for customizing your devenv.
```
{config, pkgs, ...}: { }
```

Create a nix flake in the root of your repo by generating a flake.nix file with the following content:

{
    inputs = {
        # Change 'nixos-23.11' to whichever cut of the nixpkgs repository
        # you want to use in your project. This will NOT impact the Panfactum stack at all.
        # For available versions, see https://github.com/NixOS/nixpkgs
        # We recommend using the version that is supported here:
        # https://search.nixos.org/packages (updated every 6 mo)
        pkgs.url = "github:NixOS/nixpkgs/nixos-23.11";

        # Change 'main' to be the release version that you desire
        # (or keep 'main' if you want to use the rolling release)
        # Ensure that this matches the version you use for your infrastructure modules
        panfactum.url = "github:Panfactum/stack/main";
    };

    outputs = { self, panfactum, pkgs, ... } @ inputs: {
        devShells = panfactum.lib.mkDevShells {
            inherit pkgs;
            modules = [ (import ./devenv.nix )];
        };
    };
}

Run git add flake.nix devenv.nix to register the flake and devenv file.
Run nix flake update. A flake.lock lockfile should be generated. This should be committed to version control alongside the flake.nix.
Test that you are able to instantiate the development environment via nix develop --impure. If everything is working, you should see multiple environment variables when you run printenv | grep DEVENV. You may see several warnings which we will resolve in subsequent setup steps.

Integrate direnv

direnv provides a set of shell hooks that will automatically activate your devenv when you navigate to the repo in your terminal. Additionally, it will automatically reload if there are any changes to the devenv definition and unload when you leave the repo directory.

This is controlled via a .envrc file that should exist in the root of your repository. When you instantiated the developer environment in the previous step, you should have seen a warning about this file.

Run pf-update-envrc to create / update the file.

You should now see a warning saying that the file is blocked. Run direnv allow to allow the developer environment to automatically instantiate.

Setting Global Environment Variables

A handful of environment variables need to be set in order to tailor the behavior of the Panfactum stack in your repo and organization.

Committed

We expect you to provide some variables in your devenv.nix file. You configure this with the env key as shown below:

{ config, pkgs, ...}: {
  env = {
    KEY = "value";
  };
}

For the full list of values you must set, please refer to these reference docs.

These changes should be committed into version control as they will be shared by all users of the repository.

Local

Each developer has settings that are specific to them. These should be set in a .env file using the dotenv syntax.

For the full list of available values, please refer to these reference docs.

This file should NOT be committed as the contents are specific to each user. However, you might want to include an example file in the repo called .env.example to aid your users.

Scaffold Standard Files

You now have the local development environment configured and are ready to begin deploying the live infrastructure that powers the Panfactum stack.

Notice that you still like have a few shell warnings that look like the following:

Terragrunt files are out of date. Run pf-update-terragrunt to update.

In later guides, we will cover how to configure these various utilities to deploy and connect to your infrastructure.

For now, you will want to run the following commands to set up the basic scaffolding and remove the warnings:

pf-update-envrc: Updates the .envrc file with the latest Panfactum values
pf-update-terragrunt: Creates the environments folder with some starter terragrunt boilerplate
pf-update-aws: Creates the AWS config folder with some starter boilerplate. Your AWS settings will eventually live here.
pf-update-kube: Creates the Kubernetes config folder with some starter boilerplate. Your Kubernetes settings will eventually live here.
pf-update-ssh: Create the SSH config folder with some starter boilerplate. Your SSH settings will eventually live here.
pf-update-gitignore: Augments the top-level .gitignore file to prevent certain Panfactum files / directories are not accidentally committed

Next Steps

Now that you have the tooling installed, we will need to prepare AWS for deploying infrastructure.

Panfactum Bootstrapping Guide:

Step 2 /20