obswiki/SECURITY_SETUP.md

ObsWiki Security Setup

This document outlines how to securely configure ObsWiki using environment variables for sensitive data.

Quick Setup

1. Copy the environment template:

   cp .env.example .env
   

2. Edit .env file with your secure values:

   nano .env
   

3. Generate a secure JWT secret:

   openssl rand -base64 32
   

Environment Variables

Required for Production

Variable	Description	Default	Security Level
JWT_SECRET	JWT token signing secret	CHANGE_ME_IN_PRODUCTION	CRITICAL
DATABASE_URL	Database connection string	sqlite:obswiki.db	Medium

Optional Authentication

Variable	Description	Required
ADMIN_USERNAME	Default admin username	No (defaults to admin)
ADMIN_PASSWORD	Default admin password	No (defaults to admin123)
ADMIN_EMAIL	Default admin email	No (defaults to admin@obswiki.local)

OAuth Providers (Optional)

GitHub OAuth

Variable	Description
GITHUB_CLIENT_ID	GitHub OAuth App Client ID
GITHUB_CLIENT_SECRET	GitHub OAuth App Client Secret

Google OAuth

Variable	Description
GOOGLE_CLIENT_ID	Google OAuth Client ID
GOOGLE_CLIENT_SECRET	Google OAuth Client Secret

LDAP Authentication (Optional)

Variable	Description
LDAP_SERVER	LDAP server URL (e.g., ldap://ldap.company.com:389)
LDAP_BIND_DN	Bind DN for LDAP authentication
LDAP_BIND_PASSWORD	Password for LDAP bind user
LDAP_USER_BASE	Base DN for user search
LDAP_USER_FILTER	LDAP filter for user search (default: (uid={}))

Security Best Practices

1. JWT Secret

• MUST be changed in production
• Use a cryptographically secure random string (32+ characters)
• Never commit to version control
• Rotate periodically

2. Database

• Use strong database credentials for non-SQLite databases
• Ensure database files have proper file permissions (600)
• Consider using database connection encryption

3. Admin Credentials

• Change default admin password immediately
• Use strong passwords (12+ characters, mixed case, numbers, symbols)
• Consider disabling the default admin after creating other admin users

4. File Permissions

• Ensure .env file has restricted permissions:

  chmod 600 .env
  

5. HTTPS in Production

• Always use HTTPS in production
• Configure reverse proxy (nginx, Apache) for TLS termination
• Use secure headers

Example Production .env

# Generate with: openssl rand -base64 32
JWT_SECRET=your-super-secure-random-string-here

# Production database
DATABASE_URL=postgresql://obswiki:secure_password@localhost/obswiki

# Secure admin credentials
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-very-secure-admin-password
ADMIN_EMAIL=admin@yourcompany.com

# Optional: GitHub OAuth
# GITHUB_CLIENT_ID=your_github_client_id
# GITHUB_CLIENT_SECRET=your_github_client_secret

Files to Never Commit

The following files are automatically ignored by .gitignore:

• .env - Your actual environment variables
• *.db - Database files
• create_admin.sql - Contains hardcoded passwords
• reset_admin.sql - Contains hardcoded passwords
• fix_admin.sql - Contains hardcoded passwords

Configuration Priority

ObsWiki loads configuration in this order (later overrides earlier):

1. Default values in code
2. config.toml file
3. Environment variables (highest priority)

This allows you to keep basic config in config.toml and override sensitive values with environment variables.

Verifying Setup

1. Check JWT secret is loaded:

   • Look for log message about config loading
   • Ensure it's not the default value

2. Verify admin user creation:

   • Look for "Created default admin user" log message
   • Check warning about default password if ADMIN_PASSWORD not set

3. Test authentication:

   • Try logging in with your admin credentials
   • Verify JWT tokens are working

Troubleshooting

JWT Secret Issues

• Error: "Invalid token" on login
• Solution: Ensure JWT_SECRET is set correctly and hasn't changed

Admin User Issues

• Error: Can't create admin user
• Solution: Check database permissions and migration status

Environment Variable Not Loading

• Error: Still using default values
• Solution: Check .env file permissions and syntax