155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# 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 |