Installing the Development Shell

Objective

Configure a git repository in your organization to use the Panfactum "devShell" which automatically installs 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 devShell

We use Nix, a package manager and programming language, to codify your local developer environment.

Using Nix, we provide a foundational devShell 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 Nix flake in the root of your repo by creating a flake.nix file with the following content:

   {
    inputs = {
      flake-utils.url = "github:numtide/flake-utils"; # Utility for generating flakes that are compatible with all operating systems
      panfactum.url = "github:panfactum/stack/edge.24-11-13"; # Make sure this matches your version of the Panfactum Stack
    };
   
    outputs = { panfactum, flake-utils, ... }@inputs:
      flake-utils.lib.eachDefaultSystem
      (system:
        {
          devShell = panfactum.lib.${system}.mkDevShell { };
        }
      );
    }
   

2. Run git add flake.nix to register the flake.

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

4. Test that you are able to instantiate the development environment via nix develop. If everything is working, you should see PF_DEVSHELL=1 when you run printenv | grep PF_DEVSHELL.

   You may also 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 devShell 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.

Repository Auth

When developing your own infrastructure modules, the infrastructure-as-code tools must be able to download this repository over HTTPS (not SSH). As result, you will need to set up the HTTPS credentials required by your hosting provider (example: GitHub).

We recommend using the Git Credential Manager for managing these credentials.

Integrate direnv

direnv provides a set of shell hooks that will automatically activate your devShell when you navigate to the repo in your terminal. Additionally, it will automatically reload if there are any changes to the devShell 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.