# ObsWiki Security Setup

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

## Quick Setup

1. **Copy the environment template:**
   ```bash
   cp .env.example .env
   ```

2. **Edit `.env` file with your secure values:**
   ```bash
   nano .env
   ```

3. **Generate a secure JWT secret:**
   ```bash
   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:
  ```bash
  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`

```bash
# 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