Skip to content

Commit 4486490

Browse files
KernelDeimosKernelDeimos
committed
doc: document configuration
1 parent 3666b9f commit 4486490

File tree

6 files changed

+277
-1
lines changed

6 files changed

+277
-1
lines changed

‎doc/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ to ask questions.
1515
## Deployers
1616

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

‎doc/self-hosters/config-vals.json.js‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
export default [
2+
{
3+
key: 'domain',
4+
description: `
5+
Domain name of the Puter instance. This may be used to generate URLs
6+
in the UI. If "allow_all_host_values" is false or undefined, the domain
7+
will be used to validate the host header of incoming requests.
8+
`,
9+
example_values: [
10+
'example.com',
11+
'subdomain.example.com'
12+
]
13+
},
14+
{
15+
key: 'protocol',
16+
description: `
17+
The protocol to use for URLs. This should be either "http" or "https".
18+
`,
19+
example_values: [
20+
'http',
21+
'https'
22+
]
23+
},
24+
{
25+
key: 'static_hosting_domain',
26+
description: `
27+
This domain name will be used for public site URLs. For example: when
28+
you right-click a directory and choose "Publish as Website".
29+
This domain should point to the same server. If you have a LAN configuration
30+
you could set this to something like
31+
\`site.192.168.555.12.nip.io\`, replacing
32+
\`192.168.555.12\` with a valid IP address belonging to the server.
33+
`
34+
},
35+
{
36+
key: 'allow_all_host_values',
37+
description: `
38+
If true, Puter will accept any host header value in incoming requests.
39+
This is useful for development, but should be disabled in production.
40+
`,
41+
},
42+
{
43+
key: 'allow_nipio_domains',
44+
description: `
45+
If true, Puter will allow requests with host headers that end in nip.io.
46+
This is useful for development, LAN, and VPN configurations.
47+
`
48+
},
49+
{
50+
key: 'http_port',
51+
description: `
52+
The port to listen on for HTTP requests.
53+
`,
54+
},
55+
{
56+
key: 'enable_public_folders',
57+
description: `
58+
If true, any /username/Public directory will be available to all
59+
users, including anonymous users.
60+
`
61+
},
62+
{
63+
key: 'disable_temp_users',
64+
description: `
65+
If true, new users will see the login/signup page instead of being
66+
automatically logged in as a temporary user.
67+
`
68+
},
69+
{
70+
key: 'disable_user_signup',
71+
description: `
72+
If true, the signup page will be disabled and the backend will not
73+
accept new user registrations.
74+
`
75+
},
76+
{
77+
key: 'disable_fallback_mechanisms',
78+
description: `
79+
A general setting to prevent any fallback behavior that might
80+
"hide" errors. It is recommended to set this to true when
81+
debugging, testing, or developing new features.
82+
`
83+
}
84+
]

‎doc/self-hosters/config.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Configuring Puter
2+
3+
## Terminology
4+
5+
- **root** - the "top level" of configuration; if a key-value pair is in/at "the root"
6+
that means it is **not in a nested object**
7+
(ex: values under "services" are **not** at the root).
8+
9+
## Config Locations
10+
11+
Running the server will generate a configuration file in one of these locations:
12+
- `config/config.json` when [Using Docker](#using-docker)
13+
- `volatile/config/config.json` in [Local Development](#local-development)
14+
- `/etc/puter/config.json` on a server (or within a Docker container)
15+
16+
## Editing Configuration
17+
18+
For a list of all possible config values, see [config_values.md](./config_values.md)
19+
20+
Instead of editing the generated `config.json`, you can make a config file
21+
that references it. This makes it easier to maintain if you frequently update
22+
Puter, since you can then just delete `config.json` to get new defaults.
23+
24+
For example, a `local.json` might look like this:
25+
26+
```json
27+
{
28+
// Always include this header
29+
"$version": "v1.1.0",
30+
"$requires": [
31+
"config.json"
32+
],
33+
"config_name": "local",
34+
35+
// Your custom configuration
36+
"domain": "my-puter.example.com"
37+
}
38+
```
39+
40+
To use `local.json` instead of `config.json` you will need to set the
41+
environment variable `PUTER_CONFIG_PROFILE=local` in the context where
42+
you are running Puter.
43+
44+
## Sample Configuration
45+
46+
The default configuration generated by Puter will look
47+
something like the following (updated 2025-02-26):
48+
49+
```json
50+
{
51+
"config_name": "generated default config",
52+
"mod_directories": [
53+
"{source}/../extensions"
54+
],
55+
"env": "dev",
56+
"nginx_mode": true,
57+
"server_id": "localhost",
58+
"http_port": "auto",
59+
"domain": "puter.localhost",
60+
"protocol": "http",
61+
"contact_email": "[email protected]",
62+
"services": {
63+
"database": {
64+
"engine": "sqlite",
65+
"path": "puter-database.sqlite"
66+
},
67+
"thumbnails": {
68+
"engine": "http"
69+
},
70+
"file-cache": {
71+
"disk_limit": 5368709120,
72+
"disk_max_size": 204800,
73+
"precache_size": 209715200,
74+
"path": "./file-cache"
75+
}
76+
},
77+
"cookie_name": "...",
78+
"jwt_secret": "...",
79+
"url_signature_secret": "...",
80+
"private_uid_secret": "...",
81+
"private_uid_namespace": "...",
82+
"": null
83+
}
84+
```
85+
86+
## Root-Level Parameters
87+
88+
- **domain** - origin for Puter. Do **not** include URL schema (the 'http(s)://' portion)
89+
-

‎doc/self-hosters/config_values.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
### `domain`
2+
3+
Domain name of the Puter instance. This may be used to generate URLs
4+
in the UI. If "allow_all_host_values" is false or undefined, the domain
5+
will be used to validate the host header of incoming requests.
6+
7+
#### Examples
8+
9+
- `"domain": "example.com"`
10+
- `"domain": "subdomain.example.com"`
11+
12+
### `protocol`
13+
14+
The protocol to use for URLs. This should be either "http" or "https".
15+
16+
#### Examples
17+
18+
- `"protocol": "http"`
19+
- `"protocol": "https"`
20+
21+
### `static_hosting_domain`
22+
23+
This domain name will be used for public site URLs. For example: when
24+
you right-click a directory and choose "Publish as Website".
25+
This domain should point to the same server. If you have a LAN configuration
26+
you could set this to something like
27+
`site.192.168.555.12.nip.io`, replacing
28+
`192.168.555.12` with a valid IP address belonging to the server.
29+
30+
31+
### `allow_all_host_values`
32+
33+
If true, Puter will accept any host header value in incoming requests.
34+
This is useful for development, but should be disabled in production.
35+
36+
37+
### `allow_nipio_domains`
38+
39+
If true, Puter will allow requests with host headers that end in nip.io.
40+
This is useful for development, LAN, and VPN configurations.
41+
42+
43+
### `http_port`
44+
45+
The port to listen on for HTTP requests.
46+
47+
48+
### `enable_public_folders`
49+
50+
If true, any /username/Public directory will be available to all
51+
users, including anonymous users.
52+
53+
54+
### `disable_temp_users`
55+
56+
If true, new users will see the login/signup page instead of being
57+
automatically logged in as a temporary user.
58+
59+
60+
### `disable_user_signup`
61+
62+
If true, the signup page will be disabled and the backend will not
63+
accept new user registrations.
64+
65+
66+
### `disable_fallback_mechanisms`
67+
68+
A general setting to prevent any fallback behavior that might
69+
"hide" errors. It is recommended to set this to true when
70+
debugging, testing, or developing new features.
71+
72+

‎doc/self-hosters/gen.js‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import dedent from 'dedent';
2+
import configVals from './config-vals.json.js';
3+
4+
const mdlib = {};
5+
mdlib.h = (out, n, str) => {
6+
out(`${'#'.repeat(n)} ${str}\n\n`);
7+
}
8+
9+
const N_START = 3;
10+
11+
const out = str => process.stdout.write(str);
12+
for ( const configVal of configVals ) {
13+
mdlib.h(out, N_START, `\`${configVal.key}\``);
14+
out(dedent(configVal.description) + '\n\n');
15+
16+
if ( configVal.example_values ) {
17+
mdlib.h(out, N_START + 1, `Examples`);
18+
for ( const example of configVal.example_values ) {
19+
out(`- \`"${configVal.key}": ${JSON.stringify(example)}\`\n`);
20+
}
21+
}
22+
23+
out('\n');
24+
25+
}

‎doc/self-hosters/instructions.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Until then, it is still possible to add apps using the **Dev Center** app.
1616

1717
## Configuration
1818

19-
Running the server will generate a configuration file in one of these locations:
19+
Running the server will generate a [configuration file](./config.md) in one of these locations:
2020
- `config/config.json` when [Using Docker](#using-docker)
2121
- `volatile/config/config.json` in [Local Development](#local-development)
2222
- `/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:
2626
To access Puter on your device, you can simply go to the address printed in
2727
the server console (usually `puter.localhost:4100`).
2828

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

0 commit comments

Comments
 (0)