Set up your environment

This guide will help you set up a working development environment on your work machine.

Machine

Below you will find all the required steps in order to configure the most basic machine setup.

1. Install VSCode or Cursor, Time Doctor and Google Chrome via the Kernel Self Service application.

2. Open Cloudflare WARP and connect to the aws virtual network.

3. Install basic tools:

    NIXPKGS_ALLOW_UNFREE=1 nix profile add --impure \
      nixpkgs#direnv \
      nixpkgs#git \
      nixpkgs#nil \
      nixpkgs#nix-direnv \
      nixpkgs#nixfmt \
      nixpkgs#nodejs_22 \
      nixpkgs#saml2aws \
      nixpkgs#sops \
      nixpkgs#terraform \
      nixpkgs#uv

4. Install Makes.

   nix profile add github:fluidattacks/makes/24.12

   Caution

   We are in the process of deprecating Makes in favor of flakes. However, some components still use it.

5. Create a GitLab account.

   Tip

   The username must follow the syntax usernameatfluid, where the username is the one before @fluidattacks in your credentials.

6. Create a SSH key.

7. Add your SSH key to your GitLab account.

8. Configure Git to sign commits using SSH.

   Tip

   Make sure you run the following command to automatically sign your commits:

   git config --global commit.gpgsign true

9. Write an email to help@fluidattacks.com requesting developer access to the Universe Repository.

Environment​

This section will guide you through setting up a terminal with AWS credentials and a code editor in an automated way every time you enter your local checkout of the Universe repository.

After this section you will have:

• A terminal with AWS credentials for the specific product you are developing.
• An editor with:
  • The source code of the Universe repository.
  • Recommended development extensions.
  • Automatic code formatters on save.
  • Auto completion and go to definition.
  • OS libraries required.

Terminal​

We’ll configure the terminal first. Once the terminal is configured, all of the applications you open from it will inherit the development environment and credentials.

At this point you should have Nix and Makes already installed in your system, so we won’t go into those details.

For maximum compatibility, we suggest you use ZSH (macOS default shell) as the command interpreter of your terminal.

Please follow these steps:

1. Make sure you have the following tools installed in your system:

   1. Determinate Nix
   2. Makes
   3. Git
   4. Direnv
   5. VSCode
   6. If you are missing any of the previous tools, refer back to the machine configuration

2. Clone the Universe repository using SSH:

   git clone git@gitlab.com:fluidattacks/universe.git

3. cd to the root of the repository and configure your Git username and email:

   git config user.name "Your Name"
   git config user.email "username@fluidattacks.com"

   Tip

   • The username must only contain the first name started in capitals and the last name started in capitals.
   • Make sure you use your corporate email.

   Example:

   git config user.name "Aureliano Buendia"
   git config user.email "abuendia@fluidattacks.com"

4. Configure direnv by adding the following lines to your ~/.zshrc shell configuration file:

   # Configure direnv
   export DIRENV_WARN_TIMEOUT=1h
   source <(direnv hook zsh)

   After making these changes, apply them with:

   source ~/.zshrc

5. cd to universe and run the following commands:

   cd universe
   direnv allow

   This will start the login process on your terminal.

6. For components that already use flakes, you need to cd into the component and run direnv allow to enter the development environment.

   cd skims
   direnv allow

Editor​

We highly recommend you use Visual Studio Code because most of the team uses it, and it works very well for our purpose.

1. You can open the universe directory, either using the File > Open Folder option in the menu or from a terminal, still within the universe repository with code ..
2. Go to the extensions tab (Ctrl+Shift+X), type @recommended, and install the recommended extensions for the workspace.

Your first commit

You have almost finished the onboarding.

Your next goal is making your first commit reach production.

1. Read the Contributing section carefully.

2. Create a new issue following the onboarding template and assign it to you.

3. Create your local branch.

   Tip

   • Branch name must be equal to GitLab username.
   • All changes you upload must be on your branch.

4. Add your name, username and email to the .mailmap file.

   Tip

   Make sure your name is in alphabetical order:

   Your Name <username@fluidattacks.com> usernameatfluid <username@fluidattacks.com>

5. Make sure your commit message follows the expected syntax.

6. Check if the commit message is valid using Makes:

   m . /common/test/commitlint

7. Push your commit to the repository.

   Tip

   • If the pipeline fails, you can see the logs of the failed jobs to get feedback about what went wrong.
   • Once the pipeline succeeds, you can then proceed to create a Merge Request.

8. Once the Merge Request is approved and merged, and every other item in the issue is done, you can go ahead and close the issue.

Troubleshooting

Here you will find typical errors and how to solve them.

Can not push to the remote repository

Make sure you:

1. Have the correct permissions to push to the repository.
2. Have correctly set up your SSH key.
3. Are using an updated version of Git (>2.40.0).