Authentication Setup

FOVEA supports two authentication modes designed for different deployment scenarios. This guide covers how to configure authentication for your deployment.

Authentication Modes Overview

Single-User Mode

Use case: Local development and testing

Characteristics:

No login required - automatic authentication
No logout functionality
Passwordless default user with limited privileges
No user management UI
Best for quick local testing and development

When to use:

Local development on your machine
Quick testing and experimentation
Single developer workflows
Environments where security is not a concern

Security note: Never use single-user mode in production or publicly accessible deployments.

Multi-User Mode

Use case: Production deployments and team collaboration

Characteristics:

Login required for all access
Full user management with sessions
Admin account with secure password
Logout functionality visible and functional
User registration (can be enabled/disabled)
Session-based authentication with HttpOnly cookies

When to use:

Production deployments
Demo servers (like demo.fovea.video)
Team collaboration environments
Any publicly accessible deployment
Environments where security and access control matter

Configuration

Environment Variables

Both modes use the FOVEA_MODE environment variable:

# Multi-user mode (production default)
FOVEA_MODE=multi-user

# Single-user mode (local development)
FOVEA_MODE=single-user

Multi-User Mode Setup

Required Configuration

Set authentication mode:
```
FOVEA_MODE=multi-user
```
Set admin password (required for database seeding):
```
ADMIN_PASSWORD=<your-secure-password>
```
Generate a secure password:
```
openssl rand -base64 32
```

Set session secret:

SESSION_SECRET=<your-random-secret>

Generate a session secret:

openssl rand -base64 32

Configure user registration:

# Allow users to self-register (good for open demos)
ALLOW_REGISTRATION=true

# Or disable registration (good for private deployments)
ALLOW_REGISTRATION=false

Complete Multi-User Example

# Authentication Configuration
FOVEA_MODE=multi-user
ALLOW_REGISTRATION=true
SESSION_SECRET=ms2/25t1EUjbKtxF99NLcTixmm0HK3xmKfJ+RPNthZA=
SESSION_TIMEOUT_DAYS=7

# Admin Account (required)
ADMIN_PASSWORD=W1AAlqE3UxNQ7HC6UjkLTyve4YMVvaSStGmLnoH3lKw=

# Optional: Test user for development
TEST_USER_PASSWORD=test123

Initial Setup Steps

Create .env file with authentication variables:

cd /path/to/fovea
cp .env.example .env
# Edit .env and set FOVEA_MODE, ADMIN_PASSWORD, SESSION_SECRET

Run database migrations:

docker compose exec backend npx prisma migrate deploy

Seed the database (creates admin user):

docker compose exec backend npm run seed

Verify admin user created:

docker compose exec backend npx prisma studio
# Check that 'admin' user exists with isAdmin=true and has a passwordHash

Test login:
- Navigate to your FOVEA instance
- You should see a login page
- Log in with username admin and your ADMIN_PASSWORD
- Verify logout button appears in user menu

Admin Account Management

Admin User Details

The seed script automatically creates an admin account:

Username: admin
Email: admin@example.com
Display Name: Administrator
Password: From ADMIN_PASSWORD environment variable
Role: Admin (can manage users, access admin panel)

Changing Admin Password

Local/Development:

# Update ADMIN_PASSWORD in .env
ADMIN_PASSWORD=new-secure-password

# Re-run seed (updates existing admin user)
npm run seed

Production (GitHub Actions):

Generate new password:
```
openssl rand -base64 32
```
Update GitHub secret:
- Go to repository Settings → Secrets → Actions
- Edit ADMIN_PASSWORD secret
- Paste new password

Trigger redeployment or manually update:

ssh into-your-server
cd /path/to/deployment
export ADMIN_PASSWORD='new-password'
docker compose exec backend npm run seed

Adding Additional Admins

Use the admin panel or API to promote users to admin:

Via Admin Panel:

Log in as admin
Navigate to Admin Panel
Select user to promote
Enable "Admin" checkbox
Save changes

Via Database (emergency access):

docker compose exec postgres psql -U fovea -d fovea -c \
  "UPDATE users SET \"isAdmin\" = true WHERE username = 'username';"

Single-User Mode Setup

Configuration

Single-user mode requires minimal configuration:

# Authentication Configuration
FOVEA_MODE=single-user

No ADMIN_PASSWORD or SESSION_SECRET required.

Behavior

Auto-authenticates with a default user (username: user)
No password required
No login or logout UI
Default user is not admin (for security)
Suitable only for local development

Setup Steps

Set mode in .env:
```
echo "FOVEA_MODE=single-user" >> .env
```
Start services:
```
docker compose up -d
```

Seed creates default user:

docker compose exec backend npm run seed

Access application:
- Navigate to http://localhost:3000
- You will be automatically logged in
- No logout button will appear

Production Deployment Example

GitHub Actions Deployment

For automated deployments (like demo.fovea.video), configure secrets:

Add GitHub Secrets:
- Repository Settings → Secrets → Actions
- Add ADMIN_PASSWORD with secure generated password
- Optionally add TEST_USER_PASSWORD for development users
Deployment workflow automatically:
- Sets FOVEA_MODE=multi-user
- Injects ADMIN_PASSWORD from secrets
- Sets ALLOW_REGISTRATION=true (or false, depending on config)
- Runs database seed after migrations
Post-deployment:
- Admin user automatically created with secure password
- Login required at https://your-domain.com
- Users can register if ALLOW_REGISTRATION=true

Manual Production Setup

Prepare environment:
```
ssh user@your-server
cd /path/to/fovea
```

Configure .env:

cat > .env <<EOF
FOVEA_MODE=multi-user
ALLOW_REGISTRATION=false
SESSION_SECRET=$(openssl rand -base64 32)
ADMIN_PASSWORD=$(openssl rand -base64 32)
# ... other configuration
EOF

Deploy services:
```
docker compose up -d --build
```

Run migrations and seed:

docker compose exec backend npx prisma migrate deploy
docker compose exec backend npm run seed

Save admin password securely:

# Extract and save admin password from .env
grep ADMIN_PASSWORD .env

Security Best Practices

Password Security

Generate strong passwords:

# Admin password (save this!)
openssl rand -base64 32

# Session secret
openssl rand -base64 32

Never commit passwords to version control
- Use .env files (gitignored)
- Use GitHub Secrets for CI/CD
- Use environment variables or secret managers
Rotate passwords regularly:
- Update ADMIN_PASSWORD quarterly
- Update SESSION_SECRET if compromised
- Re-run seed script after password changes

Session Security

Sessions use secure cookies:

HttpOnly: Prevents JavaScript access
Secure flag: HTTPS only in production
SameSite=Lax: Prevents CSRF attacks
Expiration: 7 days (30 days with "Remember Me")

Registration Security

For public demos:

ALLOW_REGISTRATION=true  # Allow anyone to register

For private deployments:

ALLOW_REGISTRATION=false  # Admin must create users

HTTPS Requirement

Always use HTTPS in production:

Cookies marked Secure (HTTPS only)
Prevents credential interception
Use reverse proxy (nginx, Traefik, Caddy)

Troubleshooting

Cannot Log In (Multi-User Mode)

Check mode configuration:

docker compose exec backend printenv | grep FOVEA_MODE
# Should show: FOVEA_MODE=multi-user

Verify admin user exists:

docker compose exec postgres psql -U fovea -d fovea -c \
  "SELECT username, \"isAdmin\", \"passwordHash\" IS NOT NULL as has_password FROM users WHERE username='admin';"

Expected output:

username | isAdmin | has_password
---------+---------+--------------
admin    | t       | t

If admin user missing, run seed:

docker compose exec backend npm run seed

Logout Button Not Visible

Check frontend detects multi-user mode:

curl http://localhost:3001/api/config
# Should return: {"mode":"multi-user","allowRegistration":true}

If showing single-user, check backend environment:

docker compose exec backend printenv | grep FOVEA_MODE

Restart backend if needed:

docker compose restart backend

If you're auto-logged in when you shouldn't be:

Clear browser cookies:
- Chrome: Settings → Privacy → Cookies → Clear
- Firefox: Settings → Privacy → Cookies and Site Data → Clear
Check mode is correct:
```
curl http://localhost:3001/api/config
```

Verify no default user with admin:

docker compose exec postgres psql -U fovea -d fovea -c \
  "SELECT username, \"isAdmin\" FROM users WHERE \"passwordHash\" IS NULL;"

Should return no results or non-admin users only.

Seed Script Fails

Error: "ADMIN_PASSWORD environment variable is required"

Solution: Set ADMIN_PASSWORD before running seed:

export ADMIN_PASSWORD=$(openssl rand -base64 32)
docker compose exec backend npm run seed

Error: "tsx: not found"

Solution: Use compiled seed script (should be automatic in Docker):

# In production container, use:
node prisma/seed.js

# In development, use:
npx tsx prisma/seed.ts

Registration Not Working

Check ALLOW_REGISTRATION:

curl http://localhost:3001/api/config
# Should show: "allowRegistration":true

If false, update environment:

# Edit .env
ALLOW_REGISTRATION=true

# Restart backend
docker compose restart backend

Migration Guide

From Single-User to Multi-User

Stop services:
```
docker compose down
```

Update .env:

FOVEA_MODE=multi-user
ADMIN_PASSWORD=$(openssl rand -base64 32)
SESSION_SECRET=$(openssl rand -base64 32)
ALLOW_REGISTRATION=false

Start services:
```
docker compose up -d
```

Run seed:

docker compose exec backend npm run seed

Verify:
- Visit your FOVEA instance
- Should see login page
- Log in with admin credentials
- Logout button should be visible

From Multi-User to Single-User

Warning: Not recommended for production. Only for development.

Update .env:
```
FOVEA_MODE=single-user
```
Restart:
```
docker compose restart backend
```
Access:
- Auto-login should occur
- No login/logout UI

Authentication Modes Overview​

Single-User Mode​

Multi-User Mode​

Configuration​

Environment Variables​

Multi-User Mode Setup​

Required Configuration​

Complete Multi-User Example​

Initial Setup Steps​

Admin Account Management​

Admin User Details​

Changing Admin Password​

Adding Additional Admins​

Single-User Mode Setup​

Configuration​

Behavior​

Setup Steps​

Production Deployment Example​

GitHub Actions Deployment​

Manual Production Setup​

Security Best Practices​

Password Security​

Session Security​

Registration Security​

HTTPS Requirement​

Troubleshooting​

Cannot Log In (Multi-User Mode)​

Logout Button Not Visible​

Auto-Login in Multi-User Mode​

Seed Script Fails​

Registration Not Working​

Migration Guide​

From Single-User to Multi-User​

From Multi-User to Single-User​

Additional Resources​

Authentication Modes Overview

Single-User Mode

Multi-User Mode

Configuration

Environment Variables

Multi-User Mode Setup

Required Configuration

Complete Multi-User Example

Initial Setup Steps

Admin Account Management

Admin User Details

Changing Admin Password

Adding Additional Admins

Single-User Mode Setup

Configuration

Behavior

Setup Steps

Production Deployment Example

GitHub Actions Deployment

Manual Production Setup

Security Best Practices

Password Security

Session Security

Registration Security

HTTPS Requirement

Troubleshooting

Cannot Log In (Multi-User Mode)

Logout Button Not Visible

Auto-Login in Multi-User Mode

Seed Script Fails

Registration Not Working

Migration Guide

From Single-User to Multi-User

From Multi-User to Single-User

Additional Resources