Gallery Docs
Documentation version
Gallery Docs

CORS configuration

The Gallery application now includes a secure CORS (Cross-Origin Resource Sharing) configuration to prevent cross-origin attacks.

Configuration#

CORS settings are configured in the main configuration file under the [CORS] section:

[CORS]
enabled = true
allowedOrigins = ["http://localhost:3000", "http://localhost:8080"]
allowCredentials = true
allowedMethods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
allowedHeaders = ["Origin", "Content-Type", "Accept", "Authorization", "X-CSRF-Token"]
exposedHeaders = []
maxAge = 86400

Settings#

  • enabled: Enable/disable CORS protection (default: true)
  • allowedOrigins: List of allowed origins (required if enabled)
  • allowCredentials: Allow cookies/credentials in cross-origin requests (default: true)
  • allowedMethods: HTTP methods to allow (default: standard REST methods)
  • allowedHeaders: HTTP headers to allow in requests (default: common headers)
  • exposedHeaders: Headers to expose to client (default: none)
  • maxAge: Max age for preflight requests in seconds (default: 86400)

Dynamic Port Matching#

The CORS middleware supports intelligent port matching:

  • Exact match: http://localhost:8080 matches exactly
  • Flexible port: http://localhost in allowed origins will match http://localhost:8080, http://localhost:3000, etc.
  • Production: https://gallery.yourdomain.com will match any port on that domain

This allows the same configuration to work across different deployment scenarios without requiring port-specific origins.

Security Features#

Origin Validation#

  • Only origins explicitly listed in allowedOrigins can access the API
  • Supports wildcard subdomains (e.g., *.example.com)
  • Warns if wildcard origin (*) is used (security risk)

Preflight Handling#

  • Properly handles OPTIONS preflight requests
  • Validates origin before processing
  • Returns appropriate headers and status codes

Middleware Integration#

  • Applied globally to all routes
  • Consistent CORS policy across the entire application
  • No individual handler CORS configuration needed

Migration from Wildcard CORS#

Previously, the application used wildcard CORS (Access-Control-Allow-Origin: *) which is a security risk. This has been replaced with:

  1. Strict origin validation - Only configured origins are allowed
  2. Centralized configuration - All CORS settings in one place
  3. Consistent policy - Applied via middleware to all routes

Default Configuration#

The default configuration allows access from:

  • http://localhost:3000 (React development server and Docker container)
  • http://localhost:8080 (Gallery server development)

For production, update allowedOrigins to include only your production domains.

Docker Deployment#

Gallery uses a single-container deployment where the frontend and backend run together in the same container. The Dockerfile exposes port 3000, which is the standard access port for the Gallery application.

Standard Docker Compose Setup#

services:
  gallery:
    image: mutablemango/gallery
    ports:
      - "3000:3000" # Map container port 3000 to host port 3000
    volumes:
      - /path/on/host/machine:/config
    restart: always

In this standard setup, users access Gallery at http://localhost:3000 or http://your-domain.com:3000.

Custom Docker Compose Setups#

If you deploy with separate containers or custom networking:

services:
  gallery:
    image: mutablemango/gallery
    ports:
      - "8080:8080"
    volumes:
      - /path/on/host/machine:/config
    restart: always

  # Separate frontend container (custom setup)
  gallery-ui:
    # Your custom frontend container
    # Would need CORS configured to allow http://gallery-ui:3000

Reverse Proxy Setups#

When using reverse proxies like Nginx or Traefik, you may need to add the proxy’s domain to allowed origins.

Development with Docker#

For local development with Docker, ensure your development origins are added:

[CORS]
allowedOrigins = ["http://localhost:3000", "http://localhost:8080", "http://your-dev-machine:3000"]

Testing#

CORS functionality is tested in gallery/utest/middleware_cors_test.go including:

  • Allowed origin requests
  • Disallowed origin requests
  • Preflight request handling
  • Disabled CORS functionality

Production Configuration#

For production deployments, update the allowedOrigins to include only your actual production domains:

[CORS]
enabled = true
allowedOrigins = ["https://gallery.yourdomain.com:3000", "https://yourdomain.com:3000"]
allowCredentials = true

Security Best Practices for Production#

  1. Use HTTPS only - Remove http:// origins in production
  2. Be specific - List exact domains instead of using wildcards
  3. Remove development origins - Don’t include localhost in production
  4. Review regularly - Periodically audit allowed origins

Reverse Proxy Considerations#

If using a reverse proxy (Nginx, Traefik, etc.), add the proxy’s domain:

[CORS]
allowedOrigins = ["https://gallery.yourdomain.com", "https://proxy.yourdomain.com"]

Recommendations#

  1. Never use wildcard origin (*) in production
  2. Specify exact origins whenever possible
  3. Use subdomain wildcards (*.example.com) sparingly
  4. Regularly review allowed origins list
  5. Monitor CORS-related logs for suspicious activity
Edit this page