Fresh Computer Setup

The following doc will walk you through the needed steps to set up your development environment so that you have all the necessary tools.

Linux setup (WSL)

In VS Code, open a new terminal to set up your Linux environment. You can do this in the VS Code terminal or your computer’s integrated terminal (see the Microsoft WSL install docs for a full walkthrough).

1. Open your computer’s integrated terminal in Administrator mode and install Linux, creating a dedicated Visory distribution:

   WSL install

   wsl --install -d Ubuntu --name Visory

   If you already have an existing distribution (Ubuntu or otherwise), this command just creates the new Visory one alongside it.

2. Verify the distribution was created:

   wsl -l

First launch password

The first time you launch a new distribution it will prompt you to create a Unix username and password for that distribution. This is separate from your Windows password. Remember this password — the terminal setup steps below run sudo commands during install.sh and will prompt you for it.

VS Code setup

Click the user profile icon in VS Code and choose Settings Sync. This will prompt you to log in — choose GitHub and sign in with your Visory credentials. If you encounter any issues accessing your account or don’t yet have credentials, let your superior know.

Once signed in, it’s recommended you turn Settings Sync on, so switching devices later won’t require redoing your preferences. Feel free to set up VS Code to suit your workflow now — see the Extensions section below for what we recommend.

Terminal setup

Clone the following repository to get the installation script for your terminal tools. We recommend using these tools even if you have preferred ones, since they already install the dependencies this repo’s projects need.

1. Clone and run the installer:

   mkdir "$HOME/.config"
   git clone https://github.com/MarkValadez/dotfiles.git ~/.config/dotfiles
   cd "$HOME/.config/dotfiles"
   ./install.sh

2. Close the terminal completely and open a new one. install.sh installs Nix, switches your default shell to zsh, and installs tools like direnv and devbox — none of this takes effect in the window you ran it from. Skipping this step causes errors like direnv: command not found.

3. Confirm the switch worked:

   echo $SHELL
   which direnv

   Both should resolve to a path. If $SHELL still shows /bin/bash, see the troubleshooting note below.

Terminal still shows bash after reopening

Check your actual login shell:

grep "^$(whoami):" /etc/passwd

• If that line ends in /bin/zsh, the switch worked at the OS level but your terminal app is opening a different profile. In VS Code, open the Command Palette (Ctrl+Shift+P) → Terminal: Select Default Profile → choose the zsh/Ubuntu profile, then open a new terminal tab.
• If it still ends in /bin/bash, re-run chsh -s $(which zsh) and fully restart the terminal app.

zsh missing from VS Code’s terminal profile list

Because Nix installs zsh to a per-user path instead of a standard system location, VS Code’s automatic profile detection may not find it, even though it’s correctly set as your login shell. If Terminal: Select Default Profile doesn’t list zsh, add it manually:

1. Find the path to your Nix-installed zsh: which zsh

2. Open Command Palette (Ctrl+Shift+P) → Preferences: Open User Settings (JSON)

3. Add a zsh entry under terminal.integrated.profiles.linux, using the path from step 1, and set it as the default:

   "terminal.integrated.profiles.linux": {
     "zsh": {
       "path": "/path/to/your/zsh"
     }
   },
   "terminal.integrated.defaultProfile.linux": "zsh"

4. Save the file, then open a new terminal tab. It should now start in zsh by default.

Harmless symlink warnings

While install.sh runs you may see messages like failed to symlink group \direnv`: No such file or directoryor the same forohmyposh. These are expected — those groups only define setup hooks and don't yet have any files to symlink in this repo. You can ignore them as long as the zshandstarship` groups symlink successfully.

This dotfiles repo and its tools are courtesy of our developer Mark Valadez — feel free to look at his other projects once you’re set up.

Terminal theme

We provide both starship and oh-my-posh for our terminal — pick whichever prompt engine you prefer and edit its theme file to personalize it. Modifying the shared template files themselves (rather than tinkering with your own copy) may cause issues with terminal functionality, so proceed at your own risk.

oh-my-posh

Theme file: ~/.config/dotfiles/Configs/ohmyposh/.config/ohmyposh/theme.omp.json.

1. Confirm oh-my-posh actually installed (it comes from Homebrew, via a separate step in install.sh):

   command -v oh-my-posh

2. Replace the contents of the theme file above with your desired theme (e.g. one downloaded from the oh-my-posh theme gallery).

3. Reload your shell:

   exec zsh

Starship

Theme file: ~/.config/dotfiles/Configs/starship/.config/starship/theme.toml.

1. Confirm starship actually installed (it comes from Nix, alongside the other CLI tools in install.sh):

   command -v starship

2. Replace the contents of the theme file above with your desired configuration (e.g. one downloaded from the starship preset gallery).

3. Reload your shell:

   exec zsh

Note

oh-my-posh is the prompt that’s actually wired up by default (via the wintermi/zsh-oh-my-posh zsh plugin in .zsh_plugins.txt). Starship’s binary and theme.toml are installed alongside it, but nothing currently calls starship init zsh — so editing theme.toml alone won’t change your prompt yet. To switch to starship day-to-day, you’ll also need to initialize it in your shell (e.g. add eval "$(starship init zsh)" to a conf.d file) and disable the oh-my-posh plugin. If you do this, let your team know so the dotfiles repo’s default can be kept in sync.

Clone the pipelines repo

direnv allow only does works inside a directory that contains an .envrc file — that’s the root of this pipelines repository, not your home directory or ~/.config/dotfiles. If you haven’t cloned it yet, create a folder to keep your projects in and clone it there:

mkdir -p ~/repos
cd ~/repos
git clone https://github.com/Visory-Analytics/pipelines.git
cd pipelines

As soon as you cd into the repo, direnv will detect the .envrc file and block it for security (it doesn’t auto-run .envrc files it hasn’t seen before) — you’ll see something like:

direnv: error /home/you/repos/pipelines/.envrc is blocked. Run `direnv allow` to approve its content

This is expected.

1. Log in to Azure first — .envrc shells out to az to resolve secrets, and will fail (or hang) without an active session. The command bellow will prompt you to a link to sign in to azure and then to select a subscription. Select visory-dev.

   az login

2. Approve the .envrc:

   direnv allow

   This lets direnv run the .envrc file, which initializes the devbox environment with devbox shell and loads the variables in .env. This completes your development environment setup.

If direnv allow/direnv reload seems to do nothing, confirm you’re in the repo root and that .envrc exists there: pwd && ls -a .envrc.

Danger

As a sanity check please ensure that .env is registered in the .gitignore as we don’t ever want to commit any .env to the repository.

Continue to Environment & Secrets to understand how credentials are resolved, then Verify Your Install.

Updating the terminal

If at any time you need to update the terminal or there is a change in the dotfiles repository, pull the latest changes:

cd ~/.config/dotfiles
git pull

Caution

This updating will change your personal configurations, as it pulls the origin code.

Extensions

This repo ships a .vscode/extensions.json at the root. When you open the pipelines folder in VS Code for the first time, it will prompt you to install these automatically — accept the prompt rather than hunting them down individually. If you dismissed it, open the Extensions panel and search @recommended.

The root list covers the Python/data-pipeline side of the repo:

Category	Extensions
Python tooling	Ruff (charliermarsh.ruff), Pylance (ms-python.vscode-pylance), debugpy, mypy type checker, Python venv switcher
Notebooks/Data	Jupyter, Data Wrangler, Rainbow CSV, Excel Viewer, LakeFS/DVC
Azure	Azure Resource Groups, Azure Storage, Cosmos DB, Azure Static Web Apps, azure-dev
SQL	SQLTools + Postgres driver
Databricks	Databricks extension
Git	Git History, Git Graph, GitHub Pull Requests
General QA	Error Lens, Code Spell Checker, Markdown Lint, YAML, Even Better TOML, ShellCheck, Shell Format

Web development (dashboard)

The root extensions.json doesn’t cover the Next.js dashboard (apps/mx_fuels_reporting_app/apps/web/). If you’re working there, also install:

• ESLint — the dashboard lints with eslint-config-next
• Tailwind CSS IntelliSense — the dashboard styles with Tailwind CSS 4

Working in docs/

Opening the docs/ subfolder on its own (e.g. via a separate VS Code window) will prompt for its own docs/.vscode/extensions.json:

• Astro — syntax highlighting and IntelliSense for .astro/.mdx files