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:
- 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 # 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
. Aflake.lock
lockfile should be generated. This should be committed to version control alongside theflake.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 runprintenv | 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.
Footnotes
-
Yes, even if you are developing microservices. ↩