aliasvault/docs/misc/dev/linux-macos-development.md

layout, title, parent, grand_parent, nav_order

layout	title	parent	grand_parent	nav_order
default	Linux/MacOS development	Development	Miscellaneous	1

Setting Up AliasVault Development Environment on Linux/MacOS

This guide will help you set up AliasVault for development on Linux or MacOS systems.

Prerequisites

1. Install .NET 10 SDK

   # On MacOS via brew:
   brew install --cask dotnet-sdk
   
   # On Linux:
   # Follow instructions at https://dotnet.microsoft.com/download/dotnet/10.0
   

2. Install Docker

   • Follow instructions at Docker Desktop
   • For Linux, you can also use the native Docker daemon

Setup Steps

1. Clone the Repository

   git clone https://github.com/aliasvault/aliasvault.git
   cd aliasvault
   

2. Install dotnet CLI EF Tools

   # Install dotnet EF tools globally
   dotnet tool install --global dotnet-ef
   
   # Add to your shell's PATH (if not already done)
   # For bash/zsh, add to ~/.bashrc or ~/.zshrc:
   export PATH="$PATH:$HOME/.dotnet/tools"
   
   # Verify installation
   dotnet ef
   

3. Start the dev database

   ./scripts/dev.sh is the single entry point for local development: it starts the dev database and runs the apps from source on a consistent, preconfigured set of ports (so the apps always find each other). Run it without arguments for an interactive menu, or use a subcommand directly:

   ./scripts/dev.sh db-start   # start the dev database (db-stop to stop it)
   

4. Run Tailwind CSS compiler

   # For Admin project
   cd apps/server/AliasVault.Admin
   npm run build:admin-css
   
   # For Client project
   cd apps/server/AliasVault.Client
   npm run build:client-css
   

5. Install Playwright for E2E tests

   # Install Playwright CLI
   dotnet tool install --global Microsoft.Playwright.CLI
   
   # Install browsers
   pwsh apps/server/Tests/AliasVault.E2ETests/bin/Debug/net10.0/playwright.ps1 install
   

6. Configure Development Settings

   When you start the client via ./scripts/dev.sh client, this file is generated automatically with the correct ApiUrl for your ports — you can skip this step. Only create wwwroot/appsettings.Development.json in the Client project manually if you run the client some other way:

   {
       "ApiUrl": "http://localhost:5100",
       "PrivateEmailDomains": ["example.tld"],
       "SupportEmail": "support@example.tld",
       "UseDebugEncryptionKey": "true",
       "CryptographyOverrideType": "Argon2Id",
       "CryptographyOverrideSettings": "{\"DegreeOfParallelism\":1,\"MemorySize\":1024,\"Iterations\":1}"
   }
   

7. Install rustup & compile from Rust to WebAssembly

   • Needed for AliasVault.Client module in case you want to run it directly from the code on your IDE (e.g. not using Docker)
   • Follow instructions at rustup and install it.
   • Add wasm32-unknown-unknown and wasm-pack:

   # Add wasm32-unknown-unknown target to your Rust installation
   rustup target add wasm32-unknown-unknown
   
   # Install wasm-pack
   cargo install wasm-pack
   

   • Run AliasVault Rust Core Build Script:

   ./core/rust/build.sh --browser
   

Running the Application

Use ./scripts/dev.sh for everything — it starts the dev database and runs each app from source on its preconfigured port. Each invocation starts one app, so open a terminal per app (or use the VS Code tasks, which fan out one call per app):

./scripts/dev.sh db-start   # start the dev database first
./scripts/dev.sh api        # then the API
./scripts/dev.sh client     # the Blazor client (writes its dev appsettings for you)
./scripts/dev.sh admin      # the admin web app
./scripts/dev.sh            # no argument → interactive menu
./scripts/dev.sh ports      # print the resolved port map

You can still run an individual project directly from your IDE (VS Code, Rider, etc.) if you prefer; ./scripts/dev.sh ports shows which ports it expects.

Troubleshooting

Database Issues

If you encounter database connection issues:

1. Check Database Status

   docker ps | grep postgres-dev
   

2. Check Logs

   docker logs aliasvault-dev-postgres-dev-1
   

3. Restart Database

   ./scripts/dev.sh db-stop
   ./scripts/dev.sh db-start
   

Common Issues

1. Permission Issues

   # Fix script permissions
   chmod +x install.sh
   

2. Port Conflicts

   • Run ./scripts/dev.sh ports to see the ports in use (defaults: API 5100, database 5109)
   • If those ports are taken, bump AV_INSTANCE in dev.env to shift the whole block

Additional Notes

• Keep your .NET SDK and Docker up to date
• The development database runs on port 5109 by default (configurable via dev.env)
• Use the debug encryption key in development for easier testing
• Store sensitive data in environment variables or user secrets

Support

If you encounter any issues not covered in this guide, please:

1. Check the GitHub Issues
2. Search for existing solutions
3. Create a new issue if needed