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 Nix

   Note

   Make sure you use the recommended multi-user installation

   Caution

   In case you get errors while installing and get stuck, make sure you follow the uninstalling guide and then try again.

2. Install Makes.

3. Install Git, Direnv, Sops, and VSCode:

   nix-env -iA nixpkgs.git nixpkgs.direnv nixpkgs.sops
   NIXPKGS_ALLOW_UNFREE=1 nix-env --install --attr vscode --file https://github.com/nixos/nixpkgs/archive/5fa16cffe329c93aa514db6bf3553e70326df6f7.tar.gz

4. Create a GitLab account.

   Tip

   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.

   Tip

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

   git config --global commit.gpgsign true

8. 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 GNU Bash as the command interpreter of your terminal.

Please follow these steps:

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

   1. 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. Add the following file in universe/.envrc.config:

   .envrc.config

   export OKTA_EMAIL=<username>@fluidattacks.com
   export OKTA_PASS=<your-password>

5. Configure direnv by adding the following lines to your ~/.bashrc file:

   ~/.bashrc

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

6. cd to universe and run the following commands:

   source ~/.bashrc
   cd universe
   direnv allow

   This will start the login process on your terminal.

   Tip

   • If you see an authentication error, make sure your email and password are correct.

   • If you see the following error:

     Error: Status Code: 404
     Error: Summary: Not Found: Resource not found: me (Session)
     ERROR: SAMLResponse tag was not found!

     Please remove your AWS Okta processor configuration directory by running:

     rm -rf ~/.aws-okta-processor/
     rm -rf ~/.aws/boto/cache

     And then try again. This error happens when AWS Okta processor tries to reuse a cached expired session.

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 . /lintGitCommitMsg

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.

Nix breaks after updating my mac

Sometimes, after updating your Mac, Nix does not work properly.

This usually happens because some macOS updates overwrite ~/.zshrc.

In order to fix this:

1. Add the following lines to your ~/.zshrc file:

   if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
     source '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
   fi

2. Restart your machine