Set up your environment | Fluid Attacks Help

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 VS Code or Cursor, Time Doctor, and Google Chrome via the Self Service application.
  2. Open Cloudflare WARP and connect to the AWS virtual network.
  3. Install basic tools:
    4. 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. Create a GitLab account.
    5. Notes
    The username must follow the syntax usernameatfluid, where the username is the one before @fluidattacks in your credentials.
  5. Create an SSH key.
  6. Add your SSH key to your GitLab account.
  7. Configure Git to sign commits using SSH.
    8. git config --global commit.gpgsign true
  8. Write an email to help@fluidattacks.com requesting developer access to the Universe Repository
    9. Notes
    Make sure to access the GitLab - Engineering app from Okta at least once, even if a SAML error appears

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:
  1. A terminal with AWS credentials for the specific product you are developing.
  2. An editor with:
    1. The source code of the Universe repository.
    2. Recommended development extensions.
    3. Automatic code formatters on save.
    4. Auto completion and go to definition.
    5. 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 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. Git
    3. Direnv
    4. VS Code
    5. If you are missing any of the previous tools, refer back to the machine configuration. 
  2. Clone the Universe repository using SSH:
    3. git clone git@gitlab.com:fluidattacks/universe.git
  3. cd to the root of the repository and configure your Git username and email:
    4. git config user.name "Your Name"

    git config user.email "username@fluidattacks.com"
    Idea
    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 
    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:
    5. # 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:
    6. git clone git@gitlab.com:fluidattacks/universe.git
  6. For components that already use flakes, you need to cd into the component and run direnv allow to enter the development environment.
    7. 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 to make 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. 
    4. Notes
    Bear in mind:
  4. The branch name must be equal to the GitLab username.
  5. All changes you upload must be on your branch.
  6. Add your name, username, and email to the .mailmap file. 
    7. Warning
    Make sure your name is in alphabetical order:
    Your Name <username@fluidattacks.com> usernameatfluid <username@fluidattacks.com>
  7. Make sure your commit message follows the expected syntax.
  8. Check if the commit message is valid. You can either push your commit to the repository and see if any errors show up on the pre-push hooks, or you can make the commit and execute the following command before pushing:
    9. nix run ./common#common-hooks
  9. Push your commit to the repository.
    10. Idea
    Tips:
  10. If the pipeline fails, you can see the logs of the failed jobs to get feedback about what went wrong.
  11. Once the pipeline succeeds, you can then proceed to create a Merge Request.
  12. 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).