Security

Journiv is designed with security and privacy as core principles. This guide covers security features, configuration options, and best practices to keep your instance secure.

Security Features

Journiv includes several built-in security features:

• JWT Authentication: Secure token-based authentication with automatic refresh tokens
• Password Hashing: Argon2id algorithm for secure password storage
• HTTPS Support: Works behind reverse proxies with SSL/TLS encryption
• OIDC/SSO: Optional integration with enterprise identity providers
• Input Validation: Comprehensive sanitization and validation of all inputs
• Rate Limiting: Protection against brute force attacks and abuse
• CORS Configuration: Control cross-origin resource sharing
• Token Expiration: Configurable access and refresh token lifetimes

Authentication & Authorization

Password Security

Journiv uses Argon2id for password hashing, which is considered one of the most secure password hashing algorithms available.

Password Requirements:

• Minimum length: 8 characters (configurable via PASSWORD_MIN_LENGTH)
• Strong passwords are recommended
• Passwords are never stored in plain text

Token Management

Journiv uses JWT (JSON Web Tokens) for authentication:

Recommendations:

• Keep access tokens short-lived (15 minutes is good)
• Use refresh tokens for longer sessions
• Rotate SECRET_KEY periodically in production

Disable User Registration

For private instances or when using OIDC exclusively, disable public signups:

DISABLE_SIGNUP=true

This prevents new users from registering while still allowing existing users to log in.

Security Settings

Required Security Configuration

SECRET_KEY (Required):

# Generate a strong secret key
openssl rand -base64 32

# Set in environment
SECRET_KEY=your-generated-secret-key-here

Important:

• Use a different SECRET_KEY for each environment
• Never commit SECRET_KEY to version control
• Rotate keys periodically in production
• Minimum 32 characters recommended

Environment-Specific Settings

Production:

ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=INFO
DISABLE_SIGNUP=false  # Set to true if using OIDC only

Development:

ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=DEBUG

HTTPS & SSL/TLS

Always use HTTPS in production. Journiv works behind reverse proxies that handle SSL/TLS termination.

Why HTTPS is Essential

• Encryption: Protects data in transit
• Authentication: Verifies server identity
• Data Integrity: Prevents tampering
• Privacy: Prevents eavesdropping

Setting Up HTTPS

1. Use a Reverse Proxy: Set up nginx, Traefik, or Caddy
2. Obtain SSL Certificate: Use Let's Encrypt (free) or commercial certificates
3. Configure Domain Scheme: Set DOMAIN_SCHEME=https in production
4. Redirect HTTP to HTTPS: Configure your reverse proxy to redirect

Reverse Proxy Examples

Traefik (Docker Compose):

services:
  journiv:
    image: swalabtech/journiv-app:latest
    container_name: journiv
    environment:
      - SECRET_KEY=your-secret-key-here
      - DOMAIN_NAME=journiv.example.com
      - DOMAIN_SCHEME=https
    volumes:
      - journiv_data:/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.journiv.rule=Host(`journiv.example.com`)"
      - "traefik.http.routers.journiv.entrypoints=websecure"
      - "traefik.http.routers.journiv.tls.certresolver=letsencrypt"
      - "traefik.http.services.journiv.loadbalancer.server.port=8000"
    restart: unless-stopped

volumes:
  journiv_data:

Key Configuration Points:

• Set DOMAIN_NAME to your domain (e.g., journiv.example.com)
• Set DOMAIN_SCHEME=https for production
• Configure Traefik labels for automatic SSL certificate management
• Ensure the reverse proxy forwards requests to port 8000 (Journiv's default port)

For nginx and Caddy examples, see the Configuration Guide.

SPA Routing Configuration

Journiv's web frontend is a Single Page Application (SPA). The simplest recommended reverse proxy setup is to forward all Journiv's traffic to backend's FastAPI

server {
    ... other server configuration ...
    server_name journiv.homelab.com;
    location / {
        proxy_pass http://journiv:8000;
    }
    ... other server configuration ...
}

This forwards all traffic to FastAPI, which can handle:

• API routes (/api)
• media routes (/media)
• SPA routes (/login, /entry/*, /oidc-finish)
• static Flutter assets (/main.dart.js, /assets/*)

OIDC/SSO Integration

Journiv supports OpenID Connect (OIDC) for Single Sign-On, allowing integration with identity providers like Keycloak, Authentik, Pocket ID, and others.

Benefits of OIDC

• Centralized Authentication: Manage users in one place
• Enhanced Security: Leverage provider's security features (2FA, MFA)
• User Management: Easier user provisioning and deprovisioning
• Compliance: Meet enterprise security requirements

OIDC Configuration

OIDC_ENABLED=true
OIDC_ISSUER=https://keycloak.example.com/realms/journiv
OIDC_CLIENT_ID=journiv-client
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=https://journiv.example.com/api/v1/oidc/callback
REDIS_URL=redis://redis:6379/0  # Required for OIDC

When using OIDC:

• Consider setting DISABLE_SIGNUP=true to prevent local account creation
• Ensure REDIS_URL is configured (required for OIDC state management)
• Verify OIDC_REDIRECT_URI matches your provider configuration

See Environment Variables for complete OIDC configuration options.

Database Security

SQLite Security

• File Permissions: Ensure database file is readable/writable only by the application user
• Backup Encryption: Encrypt backups if storing off-site
• Location: Store database in a secure, non-web-accessible directory

# Set proper permissions
chmod 600 /data/journiv.db
chown journiv:journiv /data/journiv.db

PostgreSQL Security

Connection Security:

# Use SSL connection
DATABASE_URL=postgresql://user:password@host:5432/journiv?sslmode=require

Best Practices:

• Use strong database passwords
• Restrict database access to only the application server
• Enable SSL/TLS for database connections
• Use dedicated database users with minimal privileges
• Regularly update PostgreSQL to the latest stable version

See Database Setup for more details.

Network Security

Firewall Configuration

Restrict access to your Journiv instance:

# Allow only necessary ports
# HTTP/HTTPS (if direct access)
ufw allow 80/tcp
ufw allow 443/tcp

# SSH (if managing server directly)
ufw allow 22/tcp

# Deny direct access to application port (if behind reverse proxy)
ufw deny 8000/tcp

Reverse Proxy Benefits

Using a reverse proxy provides:

• SSL/TLS Termination: Handle certificates at proxy level
• DDoS Protection: Rate limiting and connection management
• Access Control: IP whitelisting/blacklisting
• Logging: Centralized access logs
• Hide Internal Structure: Don't expose internal ports

Rate Limiting

Journiv includes built-in rate limiting to protect against abuse:

Configuration:

RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60

Adjust based on your needs. Higher limits for trusted networks, lower for public instances.

CORS Configuration

Control which domains can access your API:

ENABLE_CORS=true
CORS_ORIGINS=https://journiv.example.com,https://app.journiv.example.com
CORS_CREDENTIALS=true

Best Practices:

• Only enable CORS if needed (e.g., web app on different domain)
• Specify exact origins, avoid wildcards in production
• Use HTTPS origins only in production

File Upload Security

Control file uploads to prevent abuse:

Recommendations:

• Set appropriate limits based on your use case
• Monitor disk usage
• Consider file type restrictions at reverse proxy level

Security Checklist

Use this checklist to secure your Journiv instance:

Initial Setup

• Generate strong SECRET_KEY (minimum 32 characters)
• Set ENVIRONMENT=production in production
• Set DEBUG=false in production
• Configure DOMAIN_SCHEME=https in production
• Set up HTTPS with reverse proxy
• Configure firewall rules

Authentication

• Use strong passwords (minimum 8 characters)
• Configure appropriate token expiration times
• Set DISABLE_SIGNUP=true if using OIDC only
• Configure OIDC if needed
• Set up REDIS_URL if using OIDC

Database

• Use PostgreSQL for production (recommended)
• Set strong database passwords
• Enable SSL for PostgreSQL connections
• Set proper file permissions for SQLite
• Restrict database network access

Network

• Set up reverse proxy (nginx, Traefik, or Caddy)
• Obtain and configure SSL certificates
• Configure firewall to restrict access
• Hide internal application port
• Configure SPA routing (forward non-API routes to FastAPI)
• Set up proper CORS if needed

Monitoring & Maintenance

• Set up regular backups
• Monitor logs for suspicious activity
• Keep Journiv updated to latest version
• Keep system packages updated
• Review and rotate secrets periodically
• Monitor disk usage and file uploads

Advanced

• Configure rate limiting appropriately
• Set up monitoring and alerting
• Document your security configuration
• Test disaster recovery procedures
• Review access logs regularly

Troubleshooting

Common Security Issues

Token expiration too short:

• Increase ACCESS_TOKEN_EXPIRE_MINUTES if users experience frequent logouts
• Balance security with user experience

Rate limiting too aggressive:

• Increase RATE_LIMIT_PER_MINUTE if legitimate users are blocked
• Consider IP whitelisting for trusted networks

CORS errors:

• Verify CORS_ORIGINS includes your domain
• Check ENABLE_CORS=true is set
• Ensure origins use correct protocol (http/https)

OIDC not working:

• Verify REDIS_URL is configured (required)
• Check OIDC_REDIRECT_URI matches provider
• Verify client credentials are correct
• Check provider logs for errors

Frontend routes returning 404:

• Ensure reverse proxy forwards all non-API routes to FastAPI
• Verify SPA fallback is configured correctly (see SPA Routing Configuration)
• Check that OIDC callback routes (e.g., /oidc-finish) are reachable
• Review reverse proxy logs for routing issues

Additional Resources

• Environment Variables Reference - Complete configuration options
• Database Setup - Database security configuration
• Reverse Proxy Setup - HTTPS and SSL/TLS setup
• FAQ - Security - Common security questions

Getting Help

If you encounter security issues:

• Review the Troubleshooting Guide
• Check GitHub Issues
• Join Discord for community support

Security Vulnerabilities: If you discover a security vulnerability, please report it responsibly through GitHub security advisories rather than public issues.