managing-apps/docs/ENV_FILE_SETUP.md

.env File Setup

Overview

A .env file has been created at the project root to store environment variables primarily for Vibe Kanban worktrees. The .NET API optionally loads this file using the DotNetEnv package.

Note: .env file loading is optional - if the file doesn't exist, the application will continue normally using system environment variables and appsettings.json. This is expected behavior for normal operation.

What Was Done

1. Created .env file at project root with all environment variables
2. Added DotNetEnv package to Managing.Api.csproj
3. Updated Program.cs to automatically load .env file before configuration
4. Updated .gitignore to exclude .env files from version control

File Locations

• .env: Project root (/Users/oda/Desktop/Projects/managing-apps/.env)
• Configuration: src/Managing.Api/Program.cs (lines 34-58)

How It Works

The Program.cs file optionally searches for a .env file in multiple locations:

1. Current working directory
2. Executable directory
3. Project root (relative to bin/Debug/net8.0)
4. Current directory (absolute path)

When found, it loads the environment variables before WebApplication.CreateBuilder is called, ensuring they're available to the configuration system.

Important: If no .env file is found, the application continues normally without any warnings. This is expected behavior - the .env file is only needed for Vibe Kanban worktrees.

Environment Variables Included

The .env file contains:

• Database connection strings (PostgreSQL, Orleans)
• InfluxDB configuration
• JWT secrets
• Privy configuration
• Admin users and authorized addresses
• Feature flags
• Discord, N8n, Sentry, Flagsmith configurations
• Orleans configuration

Usage

Local Development

When running the API locally (outside Docker), the .env file will be optionally loaded if it exists:

cd src/Managing.Api
dotnet run

If .env exists, you'll see: ✅ Loaded .env file from: [path] (optional - for Vibe Kanban worktrees)

If .env doesn't exist, the application runs normally using system environment variables and appsettings.json (no message is shown).

Vibe Kanban Worktrees

When Vibe Kanban creates a worktree, configure it to copy the .env file:

In Vibe Kanban Settings → Copy Files:

.env

The API will automatically find and load the .env file from the worktree root.

Docker Containers

Docker containers continue to use environment variables set in docker-compose.yml files. The .env file is not used in Docker (environment variables are passed directly to containers).

Security

⚠️ Important: The .env file contains sensitive information and is excluded from git via .gitignore.

Never commit the .env file to version control!

Updating Environment Variables

To update environment variables:

1. Edit .env file at project root
2. Restart the application
3. The new values will be loaded automatically

Troubleshooting

.env file not found

This is normal! The .env file is optional and only needed for Vibe Kanban worktrees. If no .env file is found, the application will:

• Continue normally
• Use system environment variables
• Use appsettings.json files
• No error or warning is shown (this is expected behavior)

If you need the .env file for Vibe Kanban:

• Ensure .env exists at the project root
• Configure Vibe Kanban to copy it in "Copy Files" settings

Variables not loading

• Ensure .env file is at project root
• Check file format (KEY=VALUE, one per line)
• Verify no syntax errors in .env file
• Restart the application after changes

Priority Order

Configuration is loaded in this order (later sources override earlier ones):

1. .env file (via DotNetEnv)
2. appsettings.json
3. appsettings.{Environment}.json
4. System environment variables
5. User Secrets (Development only)

Related Files

• src/Managing.Api/Program.cs - Loads .env file
• src/Managing.Api/Managing.Api.csproj - Contains DotNetEnv package reference
• .gitignore - Excludes .env files
• scripts/create-task-compose.sh - Docker environment variables (separate from .env)