fosrl/docs
1
0
Fork 0
mirror of https://github.com/fosrl/docs.git synced 2025-05-13 05:40:41 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Format; add gerbil config notes

Browse source
This commit is contained in:
Owen Schwartz 2025-01-03 20:37:04 -05:00
parent 55cc04921e
commit b38b4fb0b4
No known key found for this signature in database
GPG key ID: 8271FDFFD9E0CCBD
1 changed files with 103 additions and 86 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

189
packages/docusaurus/docs/03-Pangolin/02-Configuration/02-config.md
View file

@ -5,105 +5,122 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
## Sections ## Sections
### app ### app
- `base_url`: string
- Example: `https://example.com` or `https://proxy.example.com` - `base_url`: string
- The url where the application is hosted. This is used for many things, including generating links, and determing the root domain for cookies, etc. - Example: `https://example.com` or `https://proxy.example.com`
- You can run Pangolin on a subdomain or root domain. Users will be redirected to this url to complete the auth step. - The url where the application is hosted. This is used for many things, including generating links, and determing the root domain for cookies, etc.
- `log_level`: string - You can run Pangolin on a subdomain or root domain. Users will be redirected to this url to complete the auth step.
- Options: `debug`, `info`, `warn`, `error` - `log_level`: string
- The log level for the application. - Options: `debug`, `info`, `warn`, `error`
- `save_logs`: boolean - The log level for the application.
- Whether to save logs to a file. Logs are saved to `config/logs/`. - `save_logs`: boolean
- Logs rotate - Whether to save logs to a file. Logs are saved to `config/logs/`.
- Max size: 20MB - Logs rotate
- Max files: 7 days - Max size: 20MB
- Max files: 7 days
### server ### server
- `external_port`: int
- The port the external facing (public) API will listen on. - `external_port`: int
- `internal_port`: int - The port the external facing (public) API will listen on.
- The port the internal private facing (private) API will listen on. - `internal_port`: int
- `next_port`: int - The port the internal private facing (private) API will listen on.
- The port the frontend server will listen on. - `next_port`: int
- `internal_hostname`: string - The port the frontend server will listen on.
- Example: `pangolin` - `internal_hostname`: string
- The hostname of the Pangolin container. This is used for internal communication between the components. - Example: `pangolin`
- If running with Docker Compose, this should be the name of the container, which is likely `pangolin`. - The hostname of the Pangolin container. This is used for internal communication between the components.
- `secure_cookies`: boolean - If running with Docker Compose, this should be the name of the container, which is likely `pangolin`.
- Whether to set the `Secure` flag on cookies. This is recommended if you are running Pangolin over HTTPS. - `secure_cookies`: boolean
- `session_cookie_name`: string - Whether to set the `Secure` flag on cookies. This is recommended if you are running Pangolin over HTTPS.
- Example: `p_session` - `session_cookie_name`: string
- The name of the session cookie. This is used to store the session token for the main application. - Example: `p_session`
- Cookies will be set for the base domain of the `base_url` config. - The name of the session cookie. This is used to store the session token for the main application.
- `resource_session_cookie_name`: string - Cookies will be set for the base domain of the `base_url` config.
- Example: `p_resource_session` - `resource_session_cookie_name`: string
- The prefix for the resource specific session cookie. When a user authenticates directly with a resource, this is used to store the session token for that resource. - Example: `p_resource_session`
- Cookies will be set for the base domain of the `base_url` config. - The prefix for the resource specific session cookie. When a user authenticates directly with a resource, this is used to store the session token for that resource.
- Cookies will be set for the base domain of the `base_url` config.
### traefik ### traefik
- `cert_resolver`: string
- Example: `letsencrypt` - `cert_resolver`: string
- The name of the Traefik certificate resolver. This must match the name of the resolver in the Traefik configuration. - Example: `letsencrypt`
- `http_entrypoint`: string - The name of the Traefik certificate resolver. This must match the name of the resolver in the Traefik configuration.
- Example: `web` - `http_entrypoint`: string
- The name of the Traefik entrypoint for HTTP traffic. This must match the name of the entrypoint in the Traefik configuration. - Example: `web`
- `https_entrypoint`: string - The name of the Traefik entrypoint for HTTP traffic. This must match the name of the entrypoint in the Traefik configuration.
- Example: `websecure` - `https_entrypoint`: string
- The name of the Traefik entrypoint for HTTPS traffic. This must match the name of the entrypoint in the Traefik configuration. - Example: `websecure`
- `prefer_wildcard_cert`: boolean - The name of the Traefik entrypoint for HTTPS traffic. This must match the name of the entrypoint in the Traefik configuration.
- Whether to prefer a wildcard certificate when generating certificates. This is useful if you want to use a wildcard certificate for the base domain and all subdomains. - `prefer_wildcard_cert`: boolean
- Before setting this to `true`, please see the docs for setting up wildcard certificates with Let's Encrypt, <a href="/Pangolin/wildcard-certs">here</a>. - Whether to prefer a wildcard certificate when generating certificates. This is useful if you want to use a wildcard certificate for the base domain and all subdomains.
- Before setting this to `true`, please see the docs for setting up wildcard certificates with Let's Encrypt, <a href="/Pangolin/wildcard-certs">here</a>.
### gerbil ### gerbil
- `start_port`: int
- This is the starting port for Wireguard tunnels that new Gerbil exit nodes will use and increment as they register with Pangolin. Advised to choose a base of a range with no conflicts.
- `base_endpoint`: string
- This is the domain name automatically included in Newt and Wireguard config for tunnel connections.
- `use_subdomain`: boolean
- If set to true, new Gerbil exit nodes will be assigned a unique subdomain off of the base domain. Advised to keep this to false.
- `subnet_group`: string
- IP address CIDR from which to choose smaller CIDR ranges for new Gerbil exit node registrations. Each "Gerbil" gets a subnet from this range.
- `block_size`: int
- The block size of the smaller CIDR ranges for new Gerbil exit node registrations.
### rate_limits ### rate_limits
- `global`: object
- The global rate limit configuration for all requests to the external Pangolin API. - `global`: object
- `window_minutes`: int - The global rate limit configuration for all requests to the external Pangolin API.
- Example: `1` - `window_minutes`: int
- The window in minutes for the rate limit. - Example: `1`
- `max_requests`: int - The window in minutes for the rate limit.
- Example: `100` - `max_requests`: int
- The maximum number of requests allowed in the window. - Example: `100`
- The maximum number of requests allowed in the window.
### email (optional) ### email (optional)
- `smtp_host`: string
- The SMTP host for sending emails. - `smtp_host`: string
- `smtp_port`: int - The SMTP host for sending emails.
- The SMTP port for sending emails. - `smtp_port`: int
- `smtp_username`: string - The SMTP port for sending emails.
- The SMTP username for sending emails. - `smtp_username`: string
- `smtp_password`: string - The SMTP username for sending emails.
- The SMTP password for sending emails. - `smtp_password`: string
- `no_reply`: string - The SMTP password for sending emails.
- Example: `no-reply@example.com` - `no_reply`: string
- The address to send emails from. This can be any email address, but it is recommended to use a no-reply address. - Example: `no-reply@example.com`
- The address to send emails from. This can be any email address, but it is recommended to use a no-reply address.
### users ### users
- `server_admin`: object
- The server admin who can always create new organizations. This user will always be created on startup. - `server_admin`: object
- `email`: string - The server admin who can always create new organizations. This user will always be created on startup.
- The email address of the server admin. - `email`: string
- `password`: string - The email address of the server admin.
- The password of the server admin. - `password`: string
- This password will always overwrite the password in the database on startup. This is useful for resetting the password. - The password of the server admin.
- The password must meet the following requirements: - This password will always overwrite the password in the database on startup. This is useful for resetting the password.
- At least 8 characters - The password must meet the following requirements:
- At least one uppercase letter - At least 8 characters
- At least one lowercase letter - At least one uppercase letter
- At least one digit - At least one lowercase letter
- At least one special character - At least one digit
- At least one special character
### flags ### flags
- `require_email_verification`: boolean
- Whether to require email verification for new users. If set to `true`, new users will need to verify their email address before they can log in. - `require_email_verification`: boolean
- Only turn this on if you have email configured. - Whether to require email verification for new users. If set to `true`, new users will need to verify their email address before they can log in.
- `signup_without_invite`: boolean - Only turn this on if you have email configured.
- Whether to allow users to sign up without an invite. If set to `false`, the "Sign Up" button will be removed from the login form. - `signup_without_invite`: boolean
- Users will still be able to sign up if they have a valid invite. - Whether to allow users to sign up without an invite. If set to `false`, the "Sign Up" button will be removed from the login form.
- `disable_user_create_org`: boolean - Users will still be able to sign up if they have a valid invite.
- Whether to allow users to create new organizations. If set to `false`, users will not be able to create new organizations. - `disable_user_create_org`: boolean
- The server admin can always create new organizations. - Whether to allow users to create new organizations. If set to `false`, users will not be able to create new organizations.
- The server admin can always create new organizations.
## Example Configuration File ## Example Configuration File
@ -134,8 +151,8 @@ gerbil:
start_port: 51820 start_port: 51820
base_endpoint: example.com base_endpoint: example.com
use_subdomain: false use_subdomain: false
block_size: 16
subnet_group: 10.0.0.0/8 subnet_group: 10.0.0.0/8
block_size: 16
rate_limits: rate_limits:
global: global: