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

Integrate the Panfactum devenv

Two fundamental tools codify your local developer environment:

1. nix: A package manager and programming language that works on all operating systems
2. 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:

1. 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, ...}: { }
   

2. 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 'edge.24-09-12' to be the release version that you desire
           # Ensure that this matches the version you use for your infrastructure modules
           panfactum.url = "github:panfactum/stack/edge.24-09-12";
       };
   
       outputs = { self, panfactum, pkgs, ... } @ inputs: {
           devShells = panfactum.lib.mkDevShells {
               inherit pkgs;
               modules = [ (import ./devenv.nix )];
           };
       };
   }
   

3. Run git add flake.nix devenv.nix to register the flake and devenv file.

4. Run nix flake update. A flake.lock lockfile should be generated. This should be committed to version control alongside the flake.nix.

5. 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.

Setting Repository Configuration Variables

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

Shared Configuration

We expect you to provide some top-level configuration values in a panfactum.yaml file in the root of your repository. See an example file here.

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

Personal Configuration

Each developer has settings that are specific to them. These should be set in a .env file using the dotenv syntax. This file will control what values get set as environment variables when the devenv launches.

For the full list of Panfactum-specific environment variables, please refer to these reference docs.

Even though your .env is personal to your, you might want to include an example file in the repo called .env.example to aid other users in your organization. The .env can contain entries that are not Panfactum-specific.

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.

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 have a shell warning that look like the following:

Your repository files are out-of-date with the current version of the Panfactum stack.

Run 'pf-update' to updates your files and resolve this warning.

Run pf-update to complete the scaffolding and resolve this warning.

Including Files in Version Control

When working with IaC, you must be careful in deciding which files are safe to commit to version control and which should remain private to you (e.g., files containing unencrypted secrets and credentials).

Throughout this guide many files will be added to your repository: some generated by you, some generated by our scaffolding scripts, and many containing secrets that you should not commit.

Fortunately, we automatically exclude any personal or sensitive files that are generated via running Panfactum-provided commands via .gitignore. Everything else should be committed as these those files are meant to be used by everyone else in your organization.

Next Steps

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