mirror of
https://github.com/aliasvault/aliasvault.git
synced 2025-12-23 22:28:22 -05:00
Update docs to include Windows instructions (#703)
This commit is contained in:
Leendert de Borst
committed by
Leendert de Borst
Leendert de Borst
parent
af24464a8d
commit
0dceeeffa4
@@ -1,7 +1,7 @@
|
||||
# Contributing to the source code
|
||||
We welcome contributions to AliasVault. Please read the guidelines on the official AliasVault docs website on how to get your local development environment setup and the general contribution guidelines:
|
||||
|
||||
https://docs.aliasvault.net/misc/dev/contributing.html
|
||||
https://docs.aliasvault.net/misc/dev/
|
||||
|
||||
> Tip: if the URL above is not available, the raw doc pages can also be found in the `docs` folder in this repository.
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ layout: default
|
||||
title: Browser Extensions
|
||||
parent: Development
|
||||
grand_parent: Miscellaneous
|
||||
nav_order: 2
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Browser Extensions
|
||||
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Contributing
|
||||
parent: Development
|
||||
grand_parent: Miscellaneous
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Contributing
|
||||
This document is a work-in-progress and will be expanded as time goes on. If you have any questions feel free to open a issue on GitHub.
|
||||
|
||||
Note: all instructions below are based on MacOS. If you are using a different operating system, you may need to adjust the commands accordingly.
|
||||
|
||||
## Getting Started
|
||||
In order to contribute to this project follow these instructions to setup your local environment:
|
||||
|
||||
### 1. Clone the repository
|
||||
```bash
|
||||
git clone https://github.com/lanedirt/AliasVault.git
|
||||
cd AliasVault
|
||||
```
|
||||
|
||||
### 2. Copy pre-commit hook script to .git/hooks directory
|
||||
{: .note }
|
||||
All commits in this repo are required to contain a reference to a GitHub issue in the format of "your commit message (#123)" where "123" references the GitHub issue number.
|
||||
|
||||
The pre-commit hook script below will check the commit message before allowing the commit to proceed. If the commit message is invalid, the commit will be aborted.
|
||||
|
||||
```bash
|
||||
# Copy the commit-msg hook script to the .git/hooks directory
|
||||
cp .github/hooks/commit-msg .git/hooks/commit-msg
|
||||
|
||||
# Make the script executable
|
||||
chmod +x .git/hooks/commit-msg
|
||||
```
|
||||
|
||||
### 3. Install the latest version of .NET SDK 9
|
||||
```bash
|
||||
# Install .NET SDK 9
|
||||
|
||||
# On MacOS via brew:
|
||||
brew install --cask dotnet-sdk
|
||||
|
||||
# On Windows via winget
|
||||
winget install Microsoft.DotNet.SDK.9
|
||||
```
|
||||
|
||||
### 4. Install dotnet CLI EF Tools
|
||||
```bash
|
||||
# Install dotnet EF tools globally
|
||||
dotnet tool install --global dotnet-ef
|
||||
# Include dotnet tools in your PATH
|
||||
nano ~/.zshrc
|
||||
# Add the following line to your .zshrc file
|
||||
export PATH="$PATH:$HOME/.dotnet/tools"
|
||||
# Start a new terminal and test that this command works:
|
||||
dotnet ef
|
||||
```
|
||||
|
||||
### 5. Install dev database
|
||||
AliasVault uses PostgreSQL as its database. In order to run the project locally from Visual Studio / Rider you will need to install the dev database. You can do this by running the following command. This will start a separate PostgreSQL instance on port 5433 accessible via the `localhost:5433` address.
|
||||
|
||||
```bash
|
||||
./install.sh configure-dev-db
|
||||
```
|
||||
|
||||
After the database is running you can start the project from Visual Studio / Rider in run or debug mode and it should be able to connect to the dev database.
|
||||
|
||||
### 6. Run Tailwind CSS compiler when changing HTML files to update compiled CSS
|
||||
```bash
|
||||
# For Admin project (in the admin project directory)
|
||||
npm run build:admin-css
|
||||
# For Client project (in the client project directory)
|
||||
npm run build:client-css
|
||||
```
|
||||
|
||||
### 7. Install Playwright in order to locally run NUnit E2E (end-to-end) tests
|
||||
```bash
|
||||
# First install PowerShell for Mac (if you don't have it already)
|
||||
brew install powershell/tap/powershell
|
||||
# Install Playwright
|
||||
dotnet tool install --global Microsoft.Playwright.CLI
|
||||
# Run Playwright install script to download local browsers
|
||||
# Note: make sure the E2E test project has been built at least once so the bin dir exists.
|
||||
pwsh src/Tests/AliasVault.E2ETests/bin/Debug/net9.0/playwright.ps1 install
|
||||
```
|
||||
|
||||
### 8. Create AliasVault.Client appsettings.Development.json
|
||||
The WASM client app supports a development specific appsettings.json file. This appsettings file is optional but can override various options to make debugging easier.
|
||||
|
||||
1. Copy `wwwroot/appsettings.json` to `wwwroot/appsettings.Development.json`
|
||||
|
||||
Here is an example file with the various options explained:
|
||||
|
||||
```json
|
||||
{
|
||||
"ApiUrl": "http://localhost:5092",
|
||||
"PrivateEmailDomains": ["example.tld"],
|
||||
"SupportEmail": "support@example.tld",
|
||||
"UseDebugEncryptionKey": "true",
|
||||
"CryptographyOverrideType" : "Argon2Id",
|
||||
"CryptographyOverrideSettings" : "{\"DegreeOfParallelism\":1,\"MemorySize\":1024,\"Iterations\":1}"
|
||||
}
|
||||
```
|
||||
|
||||
- **UseDebugEncryptionKey**
|
||||
- This setting will use a static encryption key so that if you login as a user you can refresh the page without needing to unlock the database again. This speeds up development when changing things in the WebApp WASM project. Note: the project needs to be run in "Development" mode for this setting to be used.
|
||||
|
||||
- **CryptographyOverrideType**
|
||||
- This setting allows overriding the default encryption type (Argon2id) with a different encryption type. This is useful for testing different encryption types without having to change code.
|
||||
|
||||
- **CryptographyOverrideSettings**
|
||||
- This setting allows overriding the default encryption settings (Argon2id) with different settings. This is useful for testing different encryption settings without having to change code. The default Argon2id settings are defined in the project as `Utilities/Cryptography/Cryptography.Client/Defaults.cs`. These default settings are focused on security but NOT performance. Normally for key derivation purposes the slower/heavier the algorithm the better protection against attackers. For production builds this is what we want, however in case of automated testing or debugging extra performance can be gained by tweaking (lowering) these settings.
|
||||
```
|
||||
@@ -2,5 +2,23 @@
|
||||
layout: default
|
||||
title: Development
|
||||
parent: Miscellaneous
|
||||
nav_order: 2
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Development Guide
|
||||
|
||||
Choose your platform to get started with AliasVault development:
|
||||
|
||||
## Platform-Specific Dev Guides
|
||||
|
||||
- [Linux/MacOS Development Setup](linux-macos-development.md)
|
||||
- [Windows Development Setup](windows-development.md)
|
||||
|
||||
## Common Development Topics
|
||||
|
||||
- [Browser Extensions](browser-extensions.md)
|
||||
- [PostgreSQL Commands](postgresql-commands.md)
|
||||
- [Running GitHub Actions Locally](run-github-actions-locally.md)
|
||||
- [Upgrading EF Server Model](upgrade-ef-server-model.md)
|
||||
- [Upgrading EF Client Model](upgrade-ef-client-model.md)
|
||||
- [Enabling WebAuthn PFR in Chrome](enable-webauthn-pfr-chrome.md)
|
||||
|
||||
157
docs/misc/dev/linux-macos-development.md
Normal file
157
docs/misc/dev/linux-macos-development.md
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
layout: default
|
||||
title: Linux/MacOS development
|
||||
parent: Development
|
||||
grand_parent: Miscellaneous
|
||||
nav_order: 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 9 SDK**
|
||||
```bash
|
||||
# On MacOS via brew:
|
||||
brew install --cask dotnet-sdk
|
||||
|
||||
# On Linux:
|
||||
# Follow instructions at https://dotnet.microsoft.com/download/dotnet/9.0
|
||||
```
|
||||
|
||||
2. **Install Docker**
|
||||
- Follow instructions at [Docker Desktop](https://www.docker.com/products/docker-desktop)
|
||||
- For Linux, you can also use the native Docker daemon
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. **Clone the Repository**
|
||||
```bash
|
||||
git clone https://github.com/lanedirt/AliasVault.git
|
||||
cd AliasVault
|
||||
```
|
||||
|
||||
2. **Copy pre-commit hook script**
|
||||
{: .note }
|
||||
All commits in this repo are required to contain a reference to a GitHub issue in the format of "your commit message (#123)" where "123" references the GitHub issue number.
|
||||
|
||||
```bash
|
||||
# Copy the commit-msg hook script
|
||||
cp .github/hooks/commit-msg .git/hooks/commit-msg
|
||||
chmod +x .git/hooks/commit-msg
|
||||
```
|
||||
|
||||
3. **Install dotnet CLI EF Tools**
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
4. **Install dev database**
|
||||
```bash
|
||||
./install.sh configure-dev-db
|
||||
```
|
||||
|
||||
5. **Run Tailwind CSS compiler**
|
||||
```bash
|
||||
# For Admin project
|
||||
cd src/AliasVault.Admin
|
||||
npm run build:admin-css
|
||||
|
||||
# For Client project
|
||||
cd src/AliasVault.Client
|
||||
npm run build:client-css
|
||||
```
|
||||
|
||||
6. **Install Playwright for E2E tests**
|
||||
```bash
|
||||
# Install Playwright CLI
|
||||
dotnet tool install --global Microsoft.Playwright.CLI
|
||||
|
||||
# Install browsers
|
||||
pwsh src/Tests/AliasVault.E2ETests/bin/Debug/net9.0/playwright.ps1 install
|
||||
```
|
||||
|
||||
7. **Configure Development Settings**
|
||||
Create `wwwroot/appsettings.Development.json` in the Client project:
|
||||
```json
|
||||
{
|
||||
"ApiUrl": "http://localhost:5092",
|
||||
"PrivateEmailDomains": ["example.tld"],
|
||||
"SupportEmail": "support@example.tld",
|
||||
"UseDebugEncryptionKey": "true",
|
||||
"CryptographyOverrideType": "Argon2Id",
|
||||
"CryptographyOverrideSettings": "{\"DegreeOfParallelism\":1,\"MemorySize\":1024,\"Iterations\":1}"
|
||||
}
|
||||
```
|
||||
|
||||
## Running the Application
|
||||
|
||||
1. **Start the Development Database**
|
||||
```bash
|
||||
./install.sh configure-dev-db
|
||||
```
|
||||
|
||||
2. **Run the Application**
|
||||
```bash
|
||||
# Using dotnet CLI
|
||||
cd src/AliasVault.Api
|
||||
dotnet run
|
||||
|
||||
# Or using your preferred IDE (VS Code, Rider, etc.)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database Issues
|
||||
If you encounter database connection issues:
|
||||
|
||||
1. **Check Database Status**
|
||||
```bash
|
||||
docker ps | grep postgres-dev
|
||||
```
|
||||
|
||||
2. **Check Logs**
|
||||
```bash
|
||||
docker logs aliasvault-dev-postgres-dev-1
|
||||
```
|
||||
|
||||
3. **Restart Database**
|
||||
```bash
|
||||
./install.sh configure-dev-db
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Permission Issues**
|
||||
```bash
|
||||
# Fix script permissions
|
||||
chmod +x install.sh
|
||||
```
|
||||
|
||||
2. **Port Conflicts**
|
||||
- Check if port 5433 is available for the development database
|
||||
- Check if port 5092 is available for the API
|
||||
|
||||
## Additional Notes
|
||||
|
||||
- Keep your .NET SDK and Docker up to date
|
||||
- The development database runs on port 5433 to avoid conflicts
|
||||
- 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](https://github.com/lanedirt/AliasVault/issues)
|
||||
2. Search for existing solutions
|
||||
3. Create a new issue if needed
|
||||
152
docs/misc/dev/windows-development.md
Normal file
152
docs/misc/dev/windows-development.md
Normal file
@@ -0,0 +1,152 @@
|
||||
---
|
||||
layout: default
|
||||
title: Windows development
|
||||
parent: Development
|
||||
grand_parent: Miscellaneous
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
|
||||
# Setting Up AliasVault Development Environment on Windows
|
||||
|
||||
This guide will help you set up AliasVault for development on Windows using WSL (Windows Subsystem for Linux).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Install WSL**
|
||||
- Open PowerShell as Administrator and run:
|
||||
```powershell
|
||||
wsl --install
|
||||
```
|
||||
- This will install Ubuntu by default
|
||||
- Restart your computer after installation
|
||||
|
||||
2. **Install Visual Studio 2022**
|
||||
- Download from [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/)
|
||||
- Required Workloads:
|
||||
- ASP.NET and web development
|
||||
- .NET WebAssembly development tools
|
||||
- .NET cross-platform development
|
||||
|
||||
3. **Install .NET 9 SDK**
|
||||
- Download from [.NET Downloads](https://dotnet.microsoft.com/download/dotnet/9.0)
|
||||
- Install both Windows and Linux versions (you'll need both)
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. **Clone the Repository**
|
||||
```bash
|
||||
git clone https://github.com/lanedirt/AliasVault.git
|
||||
cd AliasVault
|
||||
```
|
||||
|
||||
2. **Copy pre-commit hook script**
|
||||
{: .note }
|
||||
All commits in this repo are required to contain a reference to a GitHub issue in the format of "your commit message (#123)" where "123" references the GitHub issue number.
|
||||
|
||||
```bash
|
||||
# Copy the commit-msg hook script
|
||||
cp .github/hooks/commit-msg .git/hooks/commit-msg
|
||||
chmod +x .git/hooks/commit-msg
|
||||
```
|
||||
|
||||
3. **Configure WSL**
|
||||
- Open WSL terminal
|
||||
- Edit WSL configuration:
|
||||
```bash
|
||||
sudo nano /etc/wsl.conf
|
||||
```
|
||||
- Add the following configuration:
|
||||
```ini
|
||||
[automount]
|
||||
enabled = true
|
||||
options = "metadata,umask=22,fmask=11"
|
||||
mountFsTab = false
|
||||
|
||||
[boot]
|
||||
systemd=true
|
||||
```
|
||||
- Save the file (Ctrl+X, then Y)
|
||||
- Restart WSL from PowerShell:
|
||||
```powershell
|
||||
wsl --shutdown
|
||||
```
|
||||
|
||||
4. **Setup Development Database**
|
||||
- Open a new WSL terminal in the AliasVault directory
|
||||
- Run the development database setup:
|
||||
```bash
|
||||
./install.sh configure-dev-db
|
||||
```
|
||||
- Select option 1 to start the development database
|
||||
- Verify the database is running:
|
||||
```bash
|
||||
docker ps | grep postgres-dev
|
||||
```
|
||||
|
||||
5. **Run the Application**
|
||||
- Open the solution in Visual Studio 2022
|
||||
- Set WebApi as the startup project
|
||||
- Press F5 to run in debug mode
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database Connection Issues
|
||||
If the WebApi fails to start due to database connection issues:
|
||||
|
||||
1. **Check Database Status**
|
||||
```bash
|
||||
docker ps | grep postgres-dev
|
||||
```
|
||||
|
||||
2. **Check Database Logs**
|
||||
```bash
|
||||
docker logs aliasvault-dev-postgres-dev-1
|
||||
```
|
||||
|
||||
3. **Permission Issues**
|
||||
If you see permission errors, try:
|
||||
```bash
|
||||
sudo mkdir -p ./database/postgres
|
||||
sudo chown -R 999:999 ./database/postgres
|
||||
sudo chmod -R 700 ./database/postgres
|
||||
```
|
||||
|
||||
4. **Restart Development Database**
|
||||
```bash
|
||||
./install.sh configure-dev-db
|
||||
# Select option 2 to stop, then option 1 to start again
|
||||
```
|
||||
|
||||
### WSL Issues
|
||||
If you experience WSL-related issues:
|
||||
|
||||
1. Make sure you have the latest WSL version:
|
||||
```powershell
|
||||
wsl --update
|
||||
```
|
||||
|
||||
2. Verify WSL is running correctly:
|
||||
```powershell
|
||||
wsl --status
|
||||
```
|
||||
|
||||
3. If problems persist, try resetting WSL:
|
||||
```powershell
|
||||
wsl --shutdown
|
||||
wsl
|
||||
```
|
||||
|
||||
## Additional Notes
|
||||
|
||||
- Always run the development database before starting the WebApi project
|
||||
- Make sure you're using the correct .NET SDK version in both Windows and WSL
|
||||
- If you modify the WSL configuration, always restart WSL afterward
|
||||
- For best performance, store the project files in the Linux filesystem rather than the Windows filesystem
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter any issues not covered in this guide, please:
|
||||
1. Check the [GitHub Issues](https://github.com/lanedirt/AliasVault/issues)
|
||||
2. Search for existing solutions
|
||||
3. Create a new issue if needed
|
||||
Reference in New Issue
Block a user