geoservercloud/geoserver-acl repository overview

⁠GeoServer ACL

Advanced authorization system for GeoServer⁠ providing fine-grained access control for published geospatial resources.

⁠What is GeoServer ACL?

GeoServer ACL is an independent application service that manages access rules for GeoServer, allowing administrators to define granular authorization policies based on:

• User credentials and roles
• OWS service types (WMS, WFS, WCS, etc.)
• Workspaces and layers
• Geographic areas (spatial filtering)
• Layer attributes (attribute-level security)

GeoServer ACL works as an authorization manager that integrates with GeoServer's authentication mechanisms (Basic HTTP, OAuth2/OpenID Connect, etc.) to enforce access rules on a per-request basis.

Born as a fork of GeoFence⁠, GeoServer ACL follows the same logic for defining data access and administrative rules, making it familiar to GeoFence users.

⁠Quick Start

⁠Running with Docker

# Run with in-memory H2 database (development/testing only)
# Replace 3.0.0 with your desired version
docker run -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=dev \
  geoservercloud/geoserver-acl:3.0.0

Note: The H2 in-memory database is only suitable for development and testing. For production deployments, use PostgreSQL.

The service will be available at:

• Base URL: http://localhost:8080/acl⁠
• Swagger UI: http://localhost:8080/acl/openapi/swagger-ui/index.html⁠
• OpenAPI spec: http://localhost:8080/acl/openapi⁠

⁠Running with Docker Compose (Recommended)

Create a docker-compose.yml file:

volumes:
  acl_data:

services:
  acldb:
    image: imresamu/postgis:15-3.4
    environment:
      - POSTGRES_DB=acl
      - POSTGRES_USER=acl
      - POSTGRES_PASSWORD=acls3cr3t
    volumes:
      - acl_data:/var/lib/postgresql/data
    restart: always
    ports:
      - 6432:5432
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U acl"]
      interval: 5s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: '4.0'
          memory: 2G

  acl:
    image: geoservercloud/geoserver-acl:${TAG:-3.0.0}
    environment:
      - PG_HOST=acldb
      - PG_PORT=5432
      - PG_DB=acl
      - PG_SCHEMA=acl
      - PG_USER=acl
      - PG_PASSWORD=acls3cr3t
    ports:
      - 8080:8080
    depends_on:
      acldb:
        condition: service_healthy
        required: true

Then run:

# Using default version (3.0.0)
docker compose up -d

# Or specify a version
TAG=3.0.0 docker compose up -d

⁠Configuration

⁠Environment Variables

All configuration properties from values.yml can be overridden using environment variables with uppercase and underscores (e.g., pg.host → PG_HOST).

⁠PostgreSQL Database Configuration

⁠Security Configuration

Security Note: The default admin and geoserver users have well-known default passwords. Always override these in production using environment variables or Docker secrets:

environment:
  - ACL_USERS_ADMIN_PASSWORD=${ADMIN_PASSWORD}
  - ACL_USERS_GEOSERVER_PASSWORD=${GEOSERVER_PASSWORD}

Or using Docker secrets:

secrets:
  - acl_admin_password
  - acl_geoserver_password

environment:
  - ACL_USERS_ADMIN_PASSWORD_FILE=/run/secrets/acl_admin_password
  - ACL_USERS_GEOSERVER_PASSWORD_FILE=/run/secrets/acl_geoserver_password

Passwords can be provided as plaintext or bcrypt-encoded (prefix with {bcrypt}).

⁠Application Configuration

⁠Spring Cloud Bus (Optional)

⁠Logging Profiles

⁠Remote Debugging

For remote debugging, set:

JAVA_OPTS: -Xdebug -agentlib:jdwp=transport=dt_socket,address=*:15005,server=y,suspend=n

⁠Integration with GeoServer

To use this ACL service with GeoServer, you need to install the GeoServer ACL plugin. The plugin is available from the same release as this Docker image.

1. Download the GeoServer ACL plugin matching your GeoServer version
2. Install the plugin in your GeoServer instance
3. Configure the plugin to connect to this ACL service
4. Define access rules through the ACL API or web UI

Refer to the GeoServer ACL documentation⁠ for detailed integration instructions.

⁠API Documentation

The OpenAPI REST API allows you to:

• Manage access rules for data and administrative operations
• Define user and role-based authorization
• Configure workspace, layer, and service-level permissions
• Set up geographic and attribute-level filters

Access the interactive API documentation:

• Swagger UI: http://<host>:8080/acl/openapi/swagger-ui/index.html
• OpenAPI JSON: http://<host>:8080/acl/openapi

⁠Supported Architectures

This image supports multiple architectures:

• linux/amd64 (x86_64)
• linux/arm64 (aarch64)

⁠Volume Mounts

When using PostgreSQL (recommended for production), no persistent volumes are required in the container itself. All data is stored in the external PostgreSQL database. Use a volume for the PostgreSQL container to persist data:

volumes:
  acl_data:

services:
  acldb:
    volumes:
      - acl_data:/var/lib/postgresql/data

For development mode with H2, the in-memory database does not persist data between restarts. If you need persistence during development, configure a file-based H2 database (not recommended for production).

⁠Health Checks

The application exposes Spring Boot Actuator endpoints:

• Health: http://localhost:8080/acl/actuator/health
• Info: http://localhost:8080/acl/actuator/info

⁠Versioning

Image tags follow semantic versioning. Always use specific version tags in production for reproducible deployments:

• 3.0.0, 2.9.0 - Specific release versions (recommended for production)
• 3.0-SNAPSHOT - Development snapshot (for testing only)

Note: There is no latest tag. This is intentional to encourage explicit version pinning and ensure reproducible deployments. Always specify the exact version you want to use.

⁠Source Code & Contributing

• GitHub: https://github.com/geoserver/geoserver-acl⁠
• Issues: https://github.com/geoserver/geoserver-acl/issues⁠
• Contributing: See CONTRIBUTING.md⁠

⁠License

GeoServer ACL is Open Source software licensed under the GNU General Public License v2.0.

⁠Support

For questions, issues, or feature requests:

1. Check the documentation⁠
2. Search existing GitHub issues⁠
3. Create a new issue with detailed information about your use case

⁠Related Projects

• GeoServer⁠ - Open source server for geospatial data
• GeoServer Cloud⁠ - Cloud-native GeoServer deployment
• GeoFence⁠ - The original project that inspired GeoServer ACL