# tommylau/docker-ocserv architecture

> Architecture diagram of the GitHub repository tommylau/docker-ocserv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tommylau/docker-ocserv
- Repository: https://github.com/tommylau/docker-ocserv

## Overview

##### Project Type and Purpose
- This is a containerized VPN server project. It offers a Docker image that embeds ocserv (an OpenConnect VPN server) with built-in functionality to generate server and CA certificates, manage default users, and support different routing groups.
- The README clearly identifies that the container supports two user groups ("Route" and "All"), customizing network routing based on client group membership.

##### Analyzing the File Structure
- Key files include:
- Dockerfile – defines how the Docker image is built.
- docker-compose.yml – provides orchestration settings for running the container.
- docker-entrypoint.sh – the startup script to configure the container at runtime.
- route.py – likely used for performing routing logic or processing routing-related configurations.
- Several text files (e.g., cn-no-route.txt, domain-*.txt, groupinfo.txt, route.txt, All, Route) that probably contain configuration, domain, and group setup details.
- The flat file structure (rather than nested directories) suggests that the project’s focus is on containerizing the OpenConnect server with minimal overhead, concentrating on configuration and runtime behavior rather than a full-stack separation.

##### Relevant Architectural Insights from the README
- The README details environment variables used to generate CA and server certificates, guide on setting up users (such as creating or deleting the 'test' user), and explains the significance of volume mounting for the ocpasswd file.
- It describes network port mapping (typically TCP/UDP 443) and emphasizes that when using NO_TEST_USER, an external ocpasswd file must be provided to keep the container running.

a. Main Components to Include:
- Docker Container (ocserv Docker Image)
- Dockerfile and Build Process (depicting how the image is constructed)
- docker-compose Configuration (for container orchestration)
- Startup/Entrypoint (docker-entrypoint.sh) that initializes configuration at container start
- VPN Service (ocserv) which manages secure VPN connections
- Certificate Generation Module (using environment variables for CA and server certificate details)
- User Management Module (handling ocpasswd file and operations like add/delete/change password; highlighting how test/default user is managed)
- Routing Configuration (managed by route.py and accompanying text files that determine routing behavior based on group membership, e.g., Route and All groups)
- External Dependencies and Interfaces (client VPN connections over specified TCP/UDP ports, volume mounting for ocpasswd for persistent storage)

b. Establishing Relationships and Interactions:
- That when the container starts (via docker-entrypoint.sh), environmental configurations (such as certificate details) are read and applied.
- Both TCP and UDP port 443.
- Ocserv VPN service to:
- The Certificate Generation Module – to show that cert variables configure the CA and server cert.
- The User Management Module – emphasizing that user credentials (via ocpasswd and commands executed with docker exec) determine access.
- The Routing Component, which determines if a client falls into the "Route" group (direct access to mainland China websites) or "All" (all traffic protected).

c. Highlighting Architectural Patterns:
- The design uses a containerized microservice approach. The Docker image encapsulates all runtime necessities.
- Use of environment variables for runtime configuration, following the 12-factor app principles.
- That the configuration (via text files and scripts) is externalized and easily modifiable without changing the core application logic.

d. Technologies and Frameworks:
- Docker for containerization.
- Alpine Linux as the base image (for a small footprint).
- ocserv (OpenConnect VPN server) as the core service.
- Python (implied by route.py) for scripting or dynamic routing configuration.
- Standard UNIX shell scripting in docker-entrypoint.sh for initialization.

##### Instructing the Principal Software Engineer
- Use another for runtime components (entrypoint script, ocserv service, routing).
- Possibly a third style for external resources (client connections, mounted volumes).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Stage Subgraph
    subgraph "Build Stage"
        DBP["Docker Build Process"]:::config
        CO["Container Orchestration"]:::config
    end

    %% Container Runtime Subgraph
    subgraph "Container Runtime"
        DC["Docker Container (ocserv)"]:::runtime
        DE["Startup/Entrypoint Script"]:::runtime
        ENV["Environment Variables"]:::config
        VPN["VPN Service (ocserv)"]:::runtime
        CERT["Certificate Generation Module"]:::runtime
        USER["User Management Module"]:::runtime
        ROUTE["Routing Module"]:::runtime

        %% User Configuration Files Subgraph
        subgraph "User Config Files"
            U1["groupinfo.txt"]:::file
            U2["domain-common.txt"]:::file
            U3["domain-develop.txt"]:::file
            U4["domain-other.txt"]:::file
        end

        %% Routing Configuration Files Subgraph
        subgraph "Routing Config Files"
            R1["route.py"]:::file
            R2["route.txt"]:::file
            R3["All"]:::file
            R4["Route"]:::file
            R5["cn-no-route.txt"]:::file
        end
    end

    %% External Interface
    EXT["VPN Clients (TCP/UDP 443)"]:::external

    %% Connections from Build Stage to Container Runtime
    DBP --> DC
    CO --> DC

    %% Container Startup Process
    DC --> DE
    DE --> ENV
    DE --> VPN

    %% Environment Configurations to Modules
    ENV --> CERT
    ENV --> USER

    %% VPN Service connected to internal modules
    VPN --> CERT
    VPN --> USER
    VPN --> ROUTE

    %% Config Files integration (dotted arrows)
    U1 -.-> USER
    U2 -.-> USER
    U3 -.-> USER
    U4 -.-> USER

    R1 -.-> ROUTE
    R2 -.-> ROUTE
    R3 -.-> ROUTE
    R4 -.-> ROUTE
    R5 -.-> ROUTE

    %% External Client Connections
    EXT --> VPN

    %% Click Events
    click DBP "https://github.com/tommylau/docker-ocserv/tree/master/Dockerfile"
    click CO "https://github.com/tommylau/docker-ocserv/blob/master/docker-compose.yml"
    click DE "https://github.com/tommylau/docker-ocserv/blob/master/docker-entrypoint.sh"
    click R1 "https://github.com/tommylau/docker-ocserv/blob/master/route.py"
    click R2 "https://github.com/tommylau/docker-ocserv/blob/master/route.txt"
    click R3 "https://github.com/tommylau/docker-ocserv/tree/master/All"
    click R4 "https://github.com/tommylau/docker-ocserv/tree/master/Route"
    click R5 "https://github.com/tommylau/docker-ocserv/blob/master/cn-no-route.txt"
    click U1 "https://github.com/tommylau/docker-ocserv/blob/master/groupinfo.txt"
    click U2 "https://github.com/tommylau/docker-ocserv/blob/master/domain-common.txt"
    click U3 "https://github.com/tommylau/docker-ocserv/blob/master/domain-develop.txt"
    click U4 "https://github.com/tommylau/docker-ocserv/blob/master/domain-other.txt"

    %% Class Definitions for styling
    classDef config fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef runtime fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef file fill:#f8d7da,stroke:#842029,stroke-width:2px;
```
