doc: document configuration

2026-02-22 14:38:48 -06:00 · 2025-02-26 14:59:13 -05:00
parent 3666b9f3a2
commit 4486490039
6 changed files with 277 additions and 1 deletions
--- a/doc/README.md
+++ b/doc/README.md
@@ -15,6 +15,7 @@ to ask questions.
 ## Deployers

 - [Hosting Instructions](./self-hosters/instructions.md)
+- [Configuration](./self-hosters/config.md)
 - [Domain Setup](./self-hosters/domains.md)
 - [Support Levels](./self-hosters/support.md)

--- a/doc/self-hosters/config-vals.json.js
+++ b/doc/self-hosters/config-vals.json.js
@@ -0,0 +1,84 @@
+export default [
+    {
+        key: 'domain',
+        description: `
+            Domain name of the Puter instance. This may be used to generate URLs
+            in the UI. If "allow_all_host_values" is false or undefined, the domain
+            will be used to validate the host header of incoming requests.
+        `,
+        example_values: [
+            'example.com',
+            'subdomain.example.com'
+        ]
+    },
+    {
+        key: 'protocol',
+        description: `
+            The protocol to use for URLs. This should be either "http" or "https".
+        `,
+        example_values: [
+            'http',
+            'https'
+        ]
+    },
+    {
+        key: 'static_hosting_domain',
+        description: `
+            This domain name will be used for public site URLs. For example: when
+            you right-click a directory and choose "Publish as Website".
+            This domain should point to the same server. If you have a LAN configuration
+            you could set this to something like
+            \`site.192.168.555.12.nip.io\`, replacing
+            \`192.168.555.12\` with a valid IP address belonging to the server.
+        `
+    },
+    {
+        key: 'allow_all_host_values',
+        description: `
+            If true, Puter will accept any host header value in incoming requests.
+            This is useful for development, but should be disabled in production.
+        `,
+    },
+    {
+        key: 'allow_nipio_domains',
+        description: `
+            If true, Puter will allow requests with host headers that end in nip.io.
+            This is useful for development, LAN, and VPN configurations.
+        `
+    },
+    {
+        key: 'http_port',
+        description: `
+            The port to listen on for HTTP requests.
+        `,
+    },
+    {
+        key: 'enable_public_folders',
+        description: `
+            If true, any /username/Public directory will be available to all
+            users, including anonymous users.
+        `
+    },
+    {
+        key: 'disable_temp_users',
+        description: `
+            If true, new users will see the login/signup page instead of being
+            automatically logged in as a temporary user.
+        `
+    },
+    {
+        key: 'disable_user_signup',
+        description: `
+            If true, the signup page will be disabled and the backend will not
+            accept new user registrations.
+        `
+    },
+    {
+        key: 'disable_fallback_mechanisms',
+        description: `
+            A general setting to prevent any fallback behavior that might
+            "hide" errors. It is recommended to set this to true when
+            debugging, testing, or developing new features.
+        `
+    }
+]
--- a/doc/self-hosters/config.md
+++ b/doc/self-hosters/config.md
@@ -0,0 +1,89 @@
+# Configuring Puter
+
+## Terminology
+
+- **root** - the "top level" of configuration; if a key-value pair is in/at "the root"
+  that means it is **not in a nested object**
+  (ex: values under "services" are **not** at the root).
+
+## Config Locations
+
+Running the server will generate a configuration file in one of these locations:
+- `config/config.json` when [Using Docker](#using-docker)
+- `volatile/config/config.json` in [Local Development](#local-development)
+- `/etc/puter/config.json` on a server (or within a Docker container)
+
+## Editing Configuration
+
+For a list of all possible config values, see [config_values.md](./config_values.md)
+
+Instead of editing the generated `config.json`, you can make a config file
+that references it. This makes it easier to maintain if you frequently update
+Puter, since you can then just delete `config.json` to get new defaults.
+
+For example, a `local.json` might look like this:
+
+```json
+{
+    // Always include this header
+    "$version": "v1.1.0",
+    "$requires": [
+        "config.json"
+    ],
+    "config_name": "local",
+    
+    // Your custom configuration
+    "domain": "my-puter.example.com"
+}
+```
+
+To use `local.json` instead of `config.json` you will need to set the
+environment variable `PUTER_CONFIG_PROFILE=local` in the context where
+you are running Puter.
+
+## Sample Configuration
+
+The default configuration generated by Puter will look
+something like the following (updated 2025-02-26):
+
+```json
+{
+    "config_name": "generated default config",
+    "mod_directories": [
+        "{source}/../extensions"
+    ],
+    "env": "dev",
+    "nginx_mode": true,
+    "server_id": "localhost",
+    "http_port": "auto",
+    "domain": "puter.localhost",
+    "protocol": "http",
+    "contact_email": "hey@example.com",
+    "services": {
+        "database": {
+            "engine": "sqlite",
+            "path": "puter-database.sqlite"
+        },
+        "thumbnails": {
+            "engine": "http"
+        },
+        "file-cache": {
+            "disk_limit": 5368709120,
+            "disk_max_size": 204800,
+            "precache_size": 209715200,
+            "path": "./file-cache"
+        }
+    },
+    "cookie_name": "...",
+    "jwt_secret": "...",
+    "url_signature_secret": "...",
+    "private_uid_secret": "...",
+    "private_uid_namespace": "...",
+    "": null
+}
+```
+
+## Root-Level Parameters
+
+- **domain** - origin for Puter. Do **not** include URL schema (the 'http(s)://' portion)
+- 
--- a/doc/self-hosters/config_values.md
+++ b/doc/self-hosters/config_values.md
@@ -0,0 +1,72 @@
+### `domain`
+
+Domain name of the Puter instance. This may be used to generate URLs
+in the UI. If "allow_all_host_values" is false or undefined, the domain
+will be used to validate the host header of incoming requests.
+
+#### Examples
+
+- `"domain": "example.com"`
+- `"domain": "subdomain.example.com"`
+
+### `protocol`
+
+The protocol to use for URLs. This should be either "http" or "https".
+
+#### Examples
+
+- `"protocol": "http"`
+- `"protocol": "https"`
+
+### `static_hosting_domain`
+
+This domain name will be used for public site URLs. For example: when
+you right-click a directory and choose "Publish as Website".
+This domain should point to the same server. If you have a LAN configuration
+you could set this to something like
+`site.192.168.555.12.nip.io`, replacing
+`192.168.555.12` with a valid IP address belonging to the server.
+
+
+### `allow_all_host_values`
+
+If true, Puter will accept any host header value in incoming requests.
+This is useful for development, but should be disabled in production.
+
+
+### `allow_nipio_domains`
+
+If true, Puter will allow requests with host headers that end in nip.io.
+This is useful for development, LAN, and VPN configurations.
+
+
+### `http_port`
+
+The port to listen on for HTTP requests.
+
+
+### `enable_public_folders`
+
+If true, any /username/Public directory will be available to all
+users, including anonymous users.
+
+
+### `disable_temp_users`
+
+If true, new users will see the login/signup page instead of being
+automatically logged in as a temporary user.
+
+
+### `disable_user_signup`
+
+If true, the signup page will be disabled and the backend will not
+accept new user registrations.
+
+
+### `disable_fallback_mechanisms`
+
+A general setting to prevent any fallback behavior that might
+"hide" errors. It is recommended to set this to true when
+debugging, testing, or developing new features.
+
+
--- a/doc/self-hosters/gen.js
+++ b/doc/self-hosters/gen.js
@@ -0,0 +1,25 @@
+import dedent from 'dedent';
+import configVals from './config-vals.json.js';
+
+const mdlib = {};
+mdlib.h = (out, n, str) => {
+    out(`${'#'.repeat(n)} ${str}\n\n`);
+}
+
+const N_START = 3;
+
+const out = str => process.stdout.write(str);
+for ( const configVal of configVals ) {
+    mdlib.h(out, N_START, `\`${configVal.key}\``);
+    out(dedent(configVal.description) + '\n\n');
+    
+    if ( configVal.example_values ) {
+        mdlib.h(out, N_START + 1, `Examples`);
+        for ( const example of configVal.example_values ) {
+            out(`- \`"${configVal.key}": ${JSON.stringify(example)}\`\n`);
+        }
+    }
+
+    out('\n');
+
+}
--- a/doc/self-hosters/instructions.md
+++ b/doc/self-hosters/instructions.md
@@ -16,7 +16,7 @@ Until then, it is still possible to add apps using the **Dev Center** app.

 ## Configuration

-Running the server will generate a configuration file in one of these locations:
+Running the server will generate a [configuration file](./config.md) in one of these locations:
 - `config/config.json` when [Using Docker](#using-docker)
 - `volatile/config/config.json` in [Local Development](#local-development)
 - `/etc/puter/config.json` on a server (or within a Docker container)
@@ -26,6 +26,11 @@ Running the server will generate a configuration file in one of these locations:
 To access Puter on your device, you can simply go to the address printed in
 the server console (usually `puter.localhost:4100`).

+To access Puter from another device on LAN, enable the following configuration:
+```json
+"allow_nipio_domains": true
+```
+
 To access Puter from another device, a domain name must be configured, as well as
 an `api` subdomain. For example, `example.local` might be the domain name pointing
 to the IP address of the server running puter, and `api.example.com` must point to