finance/ENVIRONMENT_SETUP.md

Development Environment Setup Guide

Prerequisites

• Windows, macOS, or Linux
• Git
• Docker Desktop
• Visual Studio Code with Remote - Containers extension
• GitHub CLI

Initial Setup

1. Clone the Repository

   git clone https://github.com/acedanger/finance.git
   cd finance
   

2. Create Environment Files

   cp .devcontainer/.env.example .devcontainer/.env
   cp .env.example .env
   

GitHub Personal Access Token (PAT)

1. Create a new PAT:

   • Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
   • Click "Generate new token (classic)"
   • Name: finance-dev-token
   • Set expiration: 90 days (recommended)
   • Required scopes:
     • repo (Full control of private repositories)
     • read:packages (Download container images)
     • write:packages (Upload container images)
     • delete:packages (Optional: manage container versions)
     • workflow (GitHub Actions integration)

2. Configure the PAT:

   • Open .devcontainer/.env
   • Set GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

Building the Development Container

Using VS Code (Recommended)

1. Open the project in VS Code
2. When prompted, click "Reopen in Container"
   • Or press F1 and run "Dev Containers: Rebuild and Reopen in Container"

Using Command Line

1. Install the devcontainer CLI:

   npm install -g @devcontainers/cli
   

2. Build the container:

   devcontainer build .
   

3. Start the container:

   # With post-create command
   devcontainer up --workspace-folder .
   
   # Skip post-create command
   devcontainer up --workspace-folder . --skip-post-create
   

Building and Pushing the Container Image

1. Ensure you're in the .devcontainer directory

2. Choose your preferred script:

   Using PowerShell:

   .\build-and-push.ps1 your_github_username
   

   Using Git Bash/Unix Shell:

   chmod +x build-and-push.sh
   ./build-and-push.sh your_github_username
   

Both scripts perform the same functions:

• Validate prerequisites (Docker, GitHub CLI)
• Load GitHub PAT from .env file
• Build the container image
• Push to GitHub Container Registry
• Provide next steps for using the image

Git Hooks

This project uses Git hooks via Husky to enforce code quality:

1. Pre-commit Hook:
   • Automatically runs Biome checks before each commit
   • Prevents committing code with linting or formatting errors
   • See HOOKS.md for more details and usage instructions

Pre-commit Hooks

The project uses Git hooks to enforce code quality standards automatically when committing changes.

Setup

Husky is used to manage Git hooks and is automatically installed and configured when you run npm install. No manual setup is required.

Available Hooks

1. pre-commit: Runs before each commit to ensure code quality
   • Runs Biome.js to check and auto-fix formatting and path alias usage
   • Runs TypeScript type checking
   • Auto-stages files fixed by Biome.js

Bypassing Hooks

In rare cases, you may need to bypass the pre-commit hooks:

git commit --no-verify -m "Your commit message"

⚠️ Note: Only bypass hooks when absolutely necessary and ensure code quality manually.

Troubleshooting

If the pre-commit hook fails:

1. Review the error messages in the console
2. Fix the reported issues
3. Stage your changes again
4. Retry the commit

For hook execution issues:

# Reinstall husky hooks
npm run prepare

Environment Files

The project uses two separate environment files:

1. .devcontainer/.env:

   • Container-specific configuration
   • GitHub PAT
   • PostgreSQL settings
   • pgAdmin settings

2. .env:

   • Application-specific configuration
   • Development server port
   • API base URL
   • Node environment

Troubleshooting

Container Build Issues

• Ensure Docker Desktop is running
• Check that your PAT has the correct permissions
• Try rebuilding without cache: devcontainer build . --no-cache

GitHub Authentication Issues

• Verify your PAT in .devcontainer/.env
• Try logging in manually: gh auth login
• Check GitHub CLI status: gh auth status

Network Issues

• If DNS resolution fails, try using different DNS servers in devcontainer.json
• Check if GitHub Container Registry (ghcr.io) is accessible
• Verify Docker network settings

VS Code Issues

• Install/update the Remote - Containers extension
• Clear VS Code's container cache
• Check VS Code's "Dev Containers" output panel for detailed logs

Common Operations

Rebuilding the Container

# Using VS Code
F1 -> "Dev Containers: Rebuild Container"

# Using CLI
devcontainer build . --no-cache

Updating the Container Image

1. Make changes to Dockerfile or devcontainer.json
2. Run the build script:

   ./build-and-push.sh your_github_username
   

3. Update image reference in devcontainer.json
4. Rebuild container in VS Code

Starting Development Server

npm run dev