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

updates for beta15

Browse source
This commit is contained in:
miloschwartz 2025-02-27 11:08:57 -05:00
parent 8b8d75992c
commit 272c5c548a
No known key found for this signature in database
4 changed files with 141 additions and 137 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -6,93 +6,97 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
### `app`
- `dashboard_url`: string
- Env: APP_DASHBOARDURL
- Example: `https://example.com` or `https://proxy.example.com`
- The url where the application is hosted. This is used for many things, including generating links.
- You can run Pangolin on a subdomain or root domain. Users will be redirected to this url to complete the auth step.
- `base_domain`: string
- Env: APP_BASEDOMAIN
- Example: `example.com`
- The base domain for the application. This is used for setting cookies and determining the base domain for resources.
- `log_level`: string
- Options: `debug`, `info`, `warn`, `error`
- The log level for the application.
- `save_logs`: boolean
- Whether to save logs to a file. Logs are saved to `config/logs/`.
- Logs rotate
- Max size: 20MB
- Max files: 7 days
- `log_failed_attempts`: boolean
- Whether to log failed authentication attempts. This is useful for security tools like Crowdsec and Fail2ban.
- `dashboard_url`: string
- Env: APP_DASHBOARDURL
- Example: `https://example.com` or `https://proxy.example.com`
- The url where the application is hosted. This is used for many things, including generating links.
- You can run Pangolin on a subdomain or root domain. Users will be redirected to this url to complete the auth step.
- `log_level`: string
- Options: `debug`, `info`, `warn`, `error`
- The log level for the application.
- `save_logs`: boolean
- Whether to save logs to a file. Logs are saved to `config/logs/`.
- Logs rotate
- Max size: 20MB
- Max files: 7 days
- `log_failed_attempts`: boolean
- Whether to log failed authentication attempts. This is useful for security tools like Crowdsec and Fail2ban.
### `server`
- `external_port`: int
- Env: SERVER_EXTERNALPORT
- The port the external facing (public) API will listen on.
- `internal_port`: int
- Env: SERVER_INTERNALPORT
- The port the internal private facing (private) API will listen on.
- `next_port`: int
- Env: SERVER_NEXTPORT
- The port the frontend server will listen on.
- `internal_hostname`: string
- Example: `pangolin`
- The hostname of the Pangolin container. This is used for internal communication between the components.
- If running with Docker Compose, this should be the name of the container, which is likely `pangolin`.
- `session_cookie_name`: string
- Example: `p_session_token`
- The name of the session cookie. This is used to store the session token for the main application.
- `resource_access_token_param`: string
- Example: `p_token`
- The query parameter used to pass the access token to the resource. Badger extracts this token and sends it to Pangolin to authenticate. This is used in direct share links that do not require a browser redirect.
- `resource_session_request_param`: string
- Example: `p_session_request`
- The query parameter used to pass the session request token to be exchanged for a real session token in Badger.
- `cors`: object (optional)
- Configuration for Cross-Origin Resource Sharing (CORS).
- `origins`: array of strings (optional)
- Example: `["https://proxy.example.com"]`
- List of allowed origins for cross-origin requests.
- `methods`: array of strings (optional)
- Example: `["GET", "POST", "PUT", "DELETE", "PATCH"]`
- HTTP methods allowed for CORS requests.
- `allowed_headers`: array of strings (optional)
- Example: `["X-CSRF-Token", "Content-Type"]`
- HTTP headers allowed in CORS requests.
- `credentials`: boolean (optional)
- Whether to allow credentials.
- Default: true
- `trust_proxy`: boolean (optional)
- Whether to trust the proxy headers (e.g., `X-Forwarded-For`) for determining the client IP address.
- Default: `true`
- `dashboard_session_length_hours`: int (optional)
- The length of time in hours that the dashboard session will last after logging in.
- Default: `720`
- `resource_session_length_hours`: int (optional)
- The length of time in hours that a session for each resource will last after logging in.
- Default: `720`
- `external_port`: int
- Env: SERVER_EXTERNALPORT
- The port the external facing (public) API will listen on.
- `internal_port`: int
- Env: SERVER_INTERNALPORT
- The port the internal private facing (private) API will listen on.
- `next_port`: int
- Env: SERVER_NEXTPORT
- The port the frontend server will listen on.
- `internal_hostname`: string
- Example: `pangolin`
- The hostname of the Pangolin container. This is used for internal communication between the components.
- If running with Docker Compose, this should be the name of the container, which is likely `pangolin`.
- `session_cookie_name`: string
- Example: `p_session_token`
- The name of the session cookie. This is used to store the session token for the main application.
- `resource_access_token_param`: string
- Example: `p_token`
- The query parameter used to pass the access token to the resource. Badger extracts this token and sends it to Pangolin to authenticate. This is used in direct share links that do not require a browser redirect.
- `resource_session_request_param`: string
- Example: `p_session_request`
- The query parameter used to pass the session request token to be exchanged for a real session token in Badger.
- `cors`: object (optional)
- Configuration for Cross-Origin Resource Sharing (CORS).
- `origins`: array of strings (optional)
- Example: `["https://proxy.example.com"]`
- List of allowed origins for cross-origin requests.
- `methods`: array of strings (optional)
- Example: `["GET", "POST", "PUT", "DELETE", "PATCH"]`
- HTTP methods allowed for CORS requests.
- `allowed_headers`: array of strings (optional)
- Example: `["X-CSRF-Token", "Content-Type"]`
- HTTP headers allowed in CORS requests.
- `credentials`: boolean (optional)
- Whether to allow credentials.
- Default: true
- `trust_proxy`: boolean (optional)
- Whether to trust the proxy headers (e.g., `X-Forwarded-For`) for determining the client IP address.
- Default: `true`
- `dashboard_session_length_hours`: int (optional)
- The length of time in hours that the dashboard session will last after logging in.
- Default: `720`
- `resource_session_length_hours`: int (optional)
- The length of time in hours that a session for each resource will last after logging in.
- Default: `720`
### `domains`
- `<domain_key>`: string
- The unique key for the domain configuration.
- `base_domain`: string
- Example: `example.com`
- `cert_resolver`: string
- Example: `letsencrypt`
- The name of the Traefik certificate resolver to use for this domain. This must match the name of the certificate resolver in the Traefik configuration.
- `prefer_wildcard_cert`: boolean
- Example: `true`
- 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.
### `traefik`
- `cert_resolver`: string
- Example: `letsencrypt`
- The name of the Traefik certificate resolver. This must match the name of the resolver in the Traefik configuration.
- `http_entrypoint`: string
- Example: `web`
- The name of the Traefik entrypoint for HTTP traffic. This must match the name of the entrypoint in the Traefik configuration.
- `https_entrypoint`: string
- Example: `websecure`
- The name of the Traefik entrypoint for HTTPS traffic. This must match the name of the entrypoint in the Traefik configuration.
- `prefer_wildcard_cert`: boolean
- 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>.
- `additional_middlewares`: array of strings (optional)
- Example: `["middleware1", "middleware2"]`
- Additional middlewares to apply to the resource router generated at runtime. These must be defined in another Traefik configuration provider like the dynamic file provider.
- `http_entrypoint`: string
- Example: `web`
- The name of the Traefik entrypoint for HTTP traffic. This must match the name of the entrypoint in the Traefik configuration.
- `https_entrypoint`: string
- Example: `websecure`
- The name of the Traefik entrypoint for HTTPS traffic. This must match the name of the entrypoint in the Traefik configuration.
- `additional_middlewares`: array of strings (optional)
- Example: `["middleware1", "middleware2"]`
- Additional middlewares to apply to the resource router generated at runtime. These must be defined in another Traefik configuration provider like the dynamic file provider.
### `gerbil`
- `start_port`: int
- Env: GERBIL_STARTPORT
- 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.
@ -110,65 +114,65 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
### `rate_limits`
- `global`: object
- The global rate limit configuration for all requests to the external Pangolin API.
- `window_minutes`: int
- Example: `1`
- The window in minutes for the rate limit.
- `max_requests`: int
- Example: `100`
- The maximum number of requests allowed in the window.
- `global`: object
- The global rate limit configuration for all requests to the external Pangolin API.
- `window_minutes`: int
- Example: `1`
- The window in minutes for the rate limit.
- `max_requests`: int
- Example: `100`
- The maximum number of requests allowed in the window.
### `email` (optional)
- `smtp_host` (optional): string
- The SMTP host for sending emails.
- `smtp_port` (optional): int
- The SMTP port for sending emails.
- `smtp_user` (optional): string
- The SMTP username for sending emails.
- `smtp_pass` (optional): string
- The SMTP password for sending emails.
- `smtp_secure` (optional): boolean
- Whether to use a secure connection when sending emails. Use this if you're using port 465.
- Default: `false`
- `no_reply` (optional): string
- Example: `no-reply@example.com`
- The address to send emails from. This can be any email address. Most often this will be the same as the `smtp_user`.
- `smtp_host` (optional): string
- The SMTP host for sending emails.
- `smtp_port` (optional): int
- The SMTP port for sending emails.
- `smtp_user` (optional): string
- The SMTP username for sending emails.
- `smtp_pass` (optional): string
- The SMTP password for sending emails.
- `smtp_secure` (optional): boolean
- Whether to use a secure connection when sending emails. Use this if you're using port 465.
- Default: `false`
- `no_reply` (optional): string
- Example: `no-reply@example.com`
- The address to send emails from. This can be any email address. Most often this will be the same as the `smtp_user`.
### `users`
- `server_admin`: object
- The server admin who can always create new organizations. This user will always be created on startup.
- `email`: string
- Env: USERS_SERVERADMIN_EMAIL
- The email address of the server admin.
- `password`: string
- Env: USERS_SERVERADMIN_PASSWORD
- The password of the server admin.
- This password will always overwrite the password in the database on startup. This is useful for resetting the password.
- The password must meet the following requirements:
- At least 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one digit
- At least one special character
- `server_admin`: object
- The server admin who can always create new organizations. This user will always be created on startup.
- `email`: string
- Env: USERS_SERVERADMIN_EMAIL
- The email address of the server admin.
- `password`: string
- Env: USERS_SERVERADMIN_PASSWORD
- The password of the server admin.
- This password will always overwrite the password in the database on startup. This is useful for resetting the password.
- The password must meet the following requirements:
- At least 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one digit
- At least one special character
### `flags` (optional)
- `require_email_verification` (optional): 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.
- Only turn this on if you have email configured.
- `disable_signup_without_invite` (optional): boolean
- Whether to allow users to sign up without an explicit invite. If set to `true`, the "Sign Up" button will be removed from the login form.
- Users will still be able to sign up if they have a valid invite.
- `disable_user_create_org` (optional): boolean
- Whether to allow users to create new organizations. If set to `true`, users will not be able to create new organizations.
- The server admin can always create new organizations.
- `allow_raw_resources` (optional): boolean
- Whether to allow users to create raw TCP/UDP resources. If set to `false`, users will only be able to create http/https resources.
- `allow_base_domain_resources` (optional): boolean
- Whether to allow users to create resources on the base domain. If set to `false`, users will only be able to create resources on subdomains.
- `require_email_verification` (optional): 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.
- Only turn this on if you have email configured.
- `disable_signup_without_invite` (optional): boolean
- Whether to allow users to sign up without an explicit invite. If set to `true`, the "Sign Up" button will be removed from the login form.
- Users will still be able to sign up if they have a valid invite.
- `disable_user_create_org` (optional): boolean
- Whether to allow users to create new organizations. If set to `true`, users will not be able to create new organizations.
- The server admin can always create new organizations.
- `allow_raw_resources` (optional): boolean
- Whether to allow users to create raw TCP/UDP resources. If set to `false`, users will only be able to create http/https resources.
- `allow_base_domain_resources` (optional): boolean
- Whether to allow users to create resources on the base domain. If set to `false`, users will only be able to create resources on subdomains.
## Example Configuration File
@ -177,10 +181,15 @@ Pangolin is configured using a `config.yml` file. The file is expected to be mou
```yaml
app:
dashboard_url: "https://example.com"
base_domain: "example.com"
log_level: "info"
save_logs: false
domains:
domain1:
base_domain: "example.com"
cert_resolver: "letsencrypt"
prefer_wildcard_cert: false
server:
external_port: 3000
internal_port: 3001
@ -194,7 +203,6 @@ traefik:
cert_resolver: "letsencrypt"
http_entrypoint: "web"
https_entrypoint: "websecure"
prefer_wildcard_cert: true
gerbil:
start_port: 51820

2
packages/docusaurus/docs/03-Pangolin/02-Configuration/03-wildcard-certs.md
View file

@ -23,7 +23,7 @@ It is highly reccommended that you read the [official Traefik documentation](htt
1. Make sure the stack is not running.
2. Update the Traefik configuration to use the DNS-01 challenge instead of the HTTP-01 challenge. This tells Traefik to use your DNS provider to create the DNS records needed for the challenge.
3. Set the `prefer_wildcard_cert` flag to `true` in the Pangolin configuration file.
3. Set the `prefer_wildcard_cert` flag to `true` in the Pangolin configuration file for your domain.
- This settings will try to encourage Traefik to request one wildcard certificate for each level of the domain used by your existing resources.
- For example: If you have two resources `blog.example.com` and `blog.subdomain.example.com`, Traefik should try to request a wildcard certificate for `*.example.com` and `*.subdomain.example.com` automatically for you.

2
packages/docusaurus/docs/03-Pangolin/03-without-tunneling.md
View file

@ -24,6 +24,4 @@ Follow existing manual install steps, but Gerbil is not required. Your Docker co
<WithoutTunnelingCompose />
After first starting the app, make sure to fill out all of your information, like `dashboard_url`, `base_domain`, etc the `config.yml` that was generated for you in the volume.
See all configuration options [here](https://docs.fossorial.io/Pangolin/Configuration/config).

4
packages/docusaurus/docs/07-roadmap.md
View file

@ -34,9 +34,7 @@ Are you experienced with authentication procedures and best practices? We would
- [ ] Remember me for authentication sessions
### Organization & Domain Management
- [ ] Support for multiple domains
- [ ] Set domain per organization
- [ ] Would need to refactor auth to support cross-site cookies
- [x] Support for multiple domains
- [x] Support for running a resource at the root domain (without subdomain)
- [x] Make this optional via a flag in the config