remove docs
+2
-1851
-36
.github/workflows/docs.yaml
-36
.github/workflows/docs.yaml
···
1
-
name: docs
2
-
3
-
on:
4
-
workflow_dispatch:
5
-
push:
6
-
branches:
7
-
- main
8
-
pull_request:
9
-
10
-
permissions:
11
-
contents: write
12
-
13
-
jobs:
14
-
deploy:
15
-
runs-on: ubuntu-latest
16
-
concurrency:
17
-
group: ${{ github.workflow }}-${{ github.ref }}
18
-
steps:
19
-
- uses: actions/checkout@v2
20
-
21
-
- name: Setup mdBook
22
-
uses: peaceiris/actions-mdbook@v2
23
-
with:
24
-
mdbook-version: "latest"
25
-
26
-
- name: Build Docs
27
-
run: mdbook build docs
28
-
29
-
- name: Deploy
30
-
uses: peaceiris/actions-gh-pages@v3
31
-
if: ${{ github.ref == 'refs/heads/main' }}
32
-
with:
33
-
github_token: ${{ secrets.GITHUB_TOKEN }}
34
-
publish_dir: docs/book
35
-
publish_branch: docs
36
-
+1
-1
.vscode/settings.json
+1
-1
.vscode/settings.json
-5
.vscode/tasks.json
-5
.vscode/tasks.json
+1
-1
README.md
+1
-1
README.md
···
31
31
32
32
- <https://docs.smallweb.run>
33
33
- <https://blog.smallweb.run>
34
-
- <https://tldraw.smallweb.run>
34
+
- <https://excalidraw.smallweb.run>
35
35
36
36
Since creating smallweb websites is so easy, you can even create super simple ones. For example, when I want to invite someone to the smallweb discord server, I just send him the link <https://discord.smallweb.run>, which maps to `~/smallweb/discord/main.ts` on my vps.
37
37
-1
docs/.gitignore
-1
docs/.gitignore
···
1
-
book
-13
docs/book.toml
-13
docs/book.toml
···
1
-
[book]
2
-
authors = ["pomdtr"]
3
-
language = "en"
4
-
multilingual = false
5
-
src = "src"
6
-
title = "Smallweb"
7
-
8
-
[build]
9
-
create-missing = false
10
-
11
-
[output.html]
12
-
edit-url-template = "https://github.com/pomdtr/smallweb/edit/main/docs/{path}"
13
-
git-repository-url = "https://github.com/pomdtr/smallweb"
-30
docs/src/SUMMARY.md
-30
docs/src/SUMMARY.md
···
1
-
# Summary
2
-
3
-
[Getting Started](./getting-started.md)
4
-
5
-
# Guides
6
-
7
-
- [Routing](./guides/routing.md)
8
-
- [HTTP Servers](./guides/server.md)
9
-
- [Cli Commands](./guides/commands.md)
10
-
- [Environment Variables](./guides/env.md)
11
-
- [Cron Tasks](./guides/cron.md)
12
-
- [Plugins](./guides/plugins.md)
13
-
- [Authentication](./guides/auth.md)
14
-
- [REST Api](./guides/rest.md)
15
-
- [App Sandbox](./guides/sandbox.md)
16
-
17
-
# Hosting
18
-
19
-
- [Localhost](./hosting/localhost/localhost.md)
20
-
- [Cloudflare Tunnel](./hosting/cloudflare/cloudflare.md)
21
-
- [VPS / Home Server](./hosting/vps.md)
22
-
- [Deno Deploy](./hosting/deno-deploy.md)
23
-
24
-
# Reference
25
-
26
-
- [Global Config](./reference/global_config.md)
27
-
- [App Config](./reference/app_config.md)
28
-
- [CLI](./reference/cli.md)
29
-
30
-
<!-- markdownlint-disable-file -->
-17
docs/src/getting-started.md
-17
docs/src/getting-started.md
···
1
-
# Getting started
2
-
3
-
## Why Smallweb ?
4
-
5
-
See <https://smallweb.run> for a quick overview of the project.
6
-
7
-
## Installation
8
-
9
-
Smallweb installations steps heavily depends on the experience you want to have with Smallweb. Here are a few options:
10
-
11
-
- [Localhost Setup](./hosting/localhost/localhost.md) - Easiest way to get started, no need for a dedicated server or a domain name. Work on MacOS and Linux.
12
-
- [Home Server Setup](./hosting/cloudflare/cloudflare.md) - Host you apps on your home server, and expose them to the internet using Cloudflare Tunnel. Requires a domain name.
13
-
- [VPS Setup](./hosting/vps.md) - Similar to the Home Server setup, but using a VPS Provider instead. Shows you how to setup a fresh Debian 12 VPS to host your smallweb apps.
14
-
15
-
## Usage
16
-
17
-
Follow the [Routing](./guides/routing.md) guide to learn more about the smallweb folder structure, and create your first app.
-64
docs/src/guides/auth.md
-64
docs/src/guides/auth.md
···
1
-
# Private Apps
2
-
3
-
You can automatically protects private apps behind a login prompt. In order to achieve this, you'll need to:
4
-
5
-
1. Add an `email` field to your global config
6
-
7
-
```json
8
-
// ~/.config/smallweb/config.json
9
-
{
10
-
"domain": "example.com",
11
-
"dir": "~/smallweb",
12
-
"email": "pomdtr@example.com"
13
-
}
14
-
```
15
-
16
-
1. Set the private field to true in your app's config.
17
-
18
-
```json
19
-
// ~/smallweb/private-app/smallweb.json
20
-
{
21
-
"private": true
22
-
}
23
-
```
24
-
25
-
The next time you'll try to access the app, you'll be prompted with a login screen (provided by lastlogin.net).
26
-
27
-
Additionaly, you can generate tokens for non-interactive clients using the `smallweb token` create command.
28
-
29
-
```sh
30
-
smallweb token create --description "CI/CD pipeline"
31
-
```
32
-
33
-
Then, you can pass this token in the `Authorization` header of your requests.
34
-
35
-
```sh
36
-
curl https://private-app.example.com -H "Authorization: Bearer <token>"
37
-
```
38
-
39
-
or alternatively, use the basic auth username.
40
-
41
-
```sh
42
-
curl https://private-app.example.com -u "<token>"
43
-
44
-
# or
45
-
curl https://<token>@private-app.example.com
46
-
```
47
-
48
-
If your app is public, but you still want to protect some routes, you can use the `privateRoutes` field in your app's config.
49
-
50
-
```json
51
-
// ~/smallweb/private-app/smallweb.json
52
-
{
53
-
"privateRoutes": ["/private/*"]
54
-
}
55
-
```
56
-
57
-
There is also a `publicRoutes` field that you can use to protect all routes except the ones listed.
58
-
59
-
```json
60
-
{
61
-
"private": true,
62
-
"publicRoutes": ["/public/*"]
63
-
}
64
-
```
-40
docs/src/guides/commands.md
-40
docs/src/guides/commands.md
···
1
-
# Adding cli commands to your app
2
-
3
-
To add a cli command to your app, you'll need to add a `run` method to your app's default export.
4
-
5
-
```ts
6
-
// File: ~/smallweb/custom-command/main.ts
7
-
export default {
8
-
run(args: string[]) {
9
-
console.log("Hello world");
10
-
}
11
-
}
12
-
```
13
-
14
-
Use `smallweb run` to execute the command:
15
-
16
-
```console
17
-
$ smallweb run custom-command
18
-
Hello world
19
-
```
20
-
21
-
## Using a cli framework
22
-
23
-
[Cliffy](https://cliffy.io/) is an excellent Deno CLI framework that you can use to build more complex CLI applications.
24
-
25
-
You can easily wire it to smallweb:
26
-
27
-
```ts
28
-
import { Command } from "jsr:@cliffy/command@1.0.0-rc.5";
29
-
30
-
const name = basename(Deno.cwd());
31
-
const command = new Command().name().action(() => {
32
-
console.log(`Hello ${name}`);
33
-
});
34
-
35
-
export default {
36
-
run(args: string[]) {
37
-
await command.parse(args);
38
-
}
39
-
}
40
-
```
-45
docs/src/guides/cron.md
-45
docs/src/guides/cron.md
···
1
-
# Cron Tasks
2
-
3
-
You can register configure cron tasks from your `smallweb.json[c]`.
4
-
5
-
```json
6
-
{
7
-
"crons": [
8
-
{
9
-
"name": "daily-task",
10
-
"schedule": "0 0 * * *",
11
-
"args": [],
12
-
}
13
-
]
14
-
}
15
-
```
16
-
17
-
The schedule field is a cron expression that defines when the task should run. It follows the standard cron syntax, with five fields separated by spaces. You can also use the following shortcuts:
18
-
19
-
- `@hourly`: Run once an hour, at the beginning of the hour.
20
-
- `@daily`: Run once a day, at midnight.
21
-
- `@weekly`: Run once a week, at midnight on Sunday.
22
-
- `@monthly`: Run once a month, at midnight on the first day of the month.
23
-
- `@yearly`: Run once a year, at midnight on January 1st.
24
-
25
-
In order to handle the cron tasks, your app default export should have a `run` method that will be called when the task is triggered.
26
-
27
-
```ts
28
-
export default {
29
-
run(_args: string[]) {
30
-
console.log("Running daily task");
31
-
}
32
-
}
33
-
```
34
-
35
-
If you want to see a list of all cron tasks, you can run:
36
-
37
-
```sh
38
-
smallweb cron ls
39
-
```
40
-
41
-
To trigger one, you can use either the `smallweb cron trigger` or the `smallweb run` command:
42
-
43
-
```sh
44
-
smallweb cron trigger daily-task
45
-
```
-33
docs/src/guides/env.md
-33
docs/src/guides/env.md
···
1
-
### Setting env variables
2
-
3
-
You can set environment variables for your app by creating a file called `.env` in the application folder.
4
-
5
-
Here is an example of a `.env` file:
6
-
7
-
```txt
8
-
BEARER_TOKEN=SECURE_TOKEN
9
-
```
10
-
11
-
Use the `Deno.env.get` method to access the environment variables in your app:
12
-
13
-
```ts
14
-
// File: ~/smallweb/demo/main.ts
15
-
export default function (req: Request) {
16
-
if (req.headers.get("Authorization") !== `Bearer ${Deno.env.get("BEARER_TOKEN")}`) {
17
-
return new Response("Unauthorized", { status: 401 });
18
-
}
19
-
20
-
return new Response(`I'm private!`, {
21
-
headers: {
22
-
"Content-Type": "text/plain",
23
-
},
24
-
});
25
-
}
26
-
```
27
-
28
-
If you want to set an environment variable for all your apps, you can create a `.env` file in the at the root of your smallweb dir.
29
-
30
-
```json
31
-
// ~/smallweb/.env
32
-
GLOBAL_VAR=GLOBAL_VALUE
33
-
```
-32
docs/src/guides/plugins.md
-32
docs/src/guides/plugins.md
···
1
-
# Smallweb Plugins
2
-
3
-
The smallweb CLI can be extennded with plugins. To create a new plugin, just add a binary to your PATH that starts with `smallweb-` and the CLI will automatically detect it.
4
-
5
-
For example, if you create a new `smallweb-choose` file in your PATH with the following content:
6
-
7
-
```sh
8
-
#!/bin/sh
9
-
10
-
# check if fzf is installed
11
-
if ! command -v fzy 2> /dev/null
12
-
then
13
-
echo "fzf could not be found" >&2
14
-
echo "Please install fzf to use this script" >&2
15
-
echo "Docs: https://github.com/junegunn/fzf?tab=readme-ov-file#installation" >&2
16
-
exit 1
17
-
fi
18
-
19
-
smallweb list | cut -f1 | fzf | xargs smallweb open
20
-
```
21
-
22
-
And make it executable with `chmod +x smallweb-choose`, you will be able to run `smallweb choose` and get an interactive list of your apps to choose from, which will then be opened in your default browser.
23
-
24
-
## Example Plugins
25
-
26
-
[simpl-site](https://github.com/iamseeley/simpl-site) can be installed as a smallweb plugin. You can install it using the following command:
27
-
28
-
```sh
29
-
deno install -Agf jsr:@iamseeley/simpl-site/smallweb-simpl-site
30
-
```
31
-
32
-
You will then be able to run `smallweb simpl-site` to create a new static site.
-126
docs/src/guides/rest.md
-126
docs/src/guides/rest.md
···
1
-
# REST API
2
-
3
-
Each smallweb installation comes with a built-in REST API. You can map it to a subdomain by creating a `smallweb.json` manifest:
4
-
5
-
```json
6
-
// ~/smallweb/api/smallweb.jsonc
7
-
{
8
-
"entrypoint": "smallweb:api",
9
-
// make sure to protect your API
10
-
"private": true,
11
-
"publicRoutes": [
12
-
// openapi manifest
13
-
"/openapi.json",
14
-
// json schemas for config files
15
-
"/schemas/*"
16
-
]
17
-
}
18
-
```
19
-
20
-
A swagger UI is available at the root of the api, allowing you to easily test the available endpoints.
21
-
22
-
## Authentication
23
-
24
-
You'll need to generate a bearer token to access the API. You can create one by running the following command:
25
-
26
-
```sh
27
-
smallweb token create --description "api token" --app <api-subdomain>
28
-
```
29
-
30
-
You'll then be able to use it to authenticate your requests using this token:
31
-
32
-
```sh
33
-
curl https://<api-domain>/v0/apps -H "Authorization: Bearer <token>"
34
-
```
35
-
36
-
Or you can just use the `smallweb api` command, which automatically authenticates your requests:
37
-
38
-
```sh
39
-
smallweb api /v0/apps
40
-
```
41
-
42
-
## Client Library
43
-
44
-
Since the API is based on OpenAPI, you can easily generate client libraries for your favorite language.
45
-
46
-
For usage in smallweb apps, I personally recommend using [feTS](https://the-guild.dev/openapi/fets/client/quick-start).
47
-
48
-
Here is an example of how you can use it (no code-gen required):
49
-
50
-
```ts
51
-
import { createClient, type NormalizeOAS } from 'npm:fets'
52
-
import type openapi from 'jsr:@smallweb/openapi@<smallweb-version>'
53
-
54
-
const client = createClient<NormalizeOAS<typeof openapi>>({
55
-
endpoint: Deno.env.get("SMALLWEB_API_URL"),
56
-
globalParams: {
57
-
headers: {
58
-
Authorization: `Bearer ${Deno.env.get("SMALLWEB_API_TOKEN")}`
59
-
}
60
-
}
61
-
})
62
-
63
-
const res = await client['/v0/apps'].get()
64
-
if (!res.ok) {
65
-
throw new Error(`Failed to fetch apps: ${res.statusText}`)
66
-
}
67
-
68
-
const apps = await res.json() // typed!
69
-
```
70
-
71
-
## Webdav Server
72
-
73
-
The rest api bundles a webdav server that you can use to manage your files. It is accessible at: `https://<api-domain>/webdav`.
74
-
75
-
You can easily connect it to any webdav client:
76
-
77
-
## Windows
78
-
79
-
1. Open the File Explorer.
80
-
2. Click on the `Computer` tab.
81
-
3. Click on `Map network drive`.
82
-
4. Enter the URL of the webdav server in the `Folder` field.
83
-
5. Click `Finish`.
84
-
6. Enter your Smallweb username and password.
85
-
7. Click `OK`.
86
-
87
-
## MacOS
88
-
89
-
1. Open the Finder.
90
-
2. Click on `Go` in the menu bar.
91
-
3. Click on `Connect to Server`.
92
-
4. Enter the URL of the webdav server in the `Server Address` field.
93
-
5. Click `Connect`.
94
-
6. Enter your Smallweb username and password.
95
-
7. Click `Connect`.
96
-
8. Click `Done`.
97
-
98
-
## Linux (Ubuntu)
99
-
100
-
1. Open Nautilus / Files.
101
-
2. Click on `Other Locations`.
102
-
3. Enter the URL of the webdav server, and prefix with `davs://` (ex: `davs://<api-domain>/webdav`).
103
-
4. Click `Connect`.
104
-
5. Enter your Smallweb username and password.
105
-
6. Click `Connect`.
106
-
107
-
## Android
108
-
109
-
[Material Files](https://play.google.com/store/apps/details?id=me.zhanghai.android.files) has built-in support for WebDAV.
110
-
111
-
## Javascript
112
-
113
-
I'm still searching for a good webdav client in javascript. The best I found so far is [webdav-client](https://www.npmjs.com/package/webdav-client), but I don't really like it.
114
-
115
-
Still, here is an example of how you can use it:
116
-
117
-
```ts
118
-
import * as webdav from 'webdav'
119
-
120
-
const webdavClient = webdav.createClient(new URL("/webdav", Deno.env.get("SMALLWEB_API_URL")).href, {
121
-
authType: webdav.AuthType.Password,
122
-
username: Deno.env.get("SMALLWEB_API_TOKEN")
123
-
})
124
-
125
-
const apps = await webdavClient.getDirectoryContents("/")
126
-
```
-23
docs/src/guides/routing.md
-23
docs/src/guides/routing.md
···
1
-
# Routing
2
-
3
-
Smallweb maps every subdomains of your root domain to a directory in your root directory.
4
-
5
-
For example with, the following configuration:
6
-
7
-
```json
8
-
// ~/.config/smallweb/config.json
9
-
{
10
-
"domain": "example.com",
11
-
"dir": "~/smallweb"
12
-
}
13
-
```
14
-
15
-
The routing system maps domains to directories as follows:
16
-
17
-
- Direct subdomain mapping:
18
-
- `api.example.com` → `~/smallweb/api`
19
-
- `blog.example.com` → `~/smallweb/blog`
20
-
21
-
- Root domain behavior:
22
-
- Requests to `example.com` automatically redirect to `www.example.com` if the `www` directory exists
23
-
- If the `www` directory does not exist, a 404 error is returned
-21
docs/src/guides/sandbox.md
-21
docs/src/guides/sandbox.md
···
1
-
# App Sandbox
2
-
3
-
Smallweb apps have access to:
4
-
5
-
- read and write access to their own directory, and the deno cache directory.
6
-
- access to the network, to make HTTP requests.
7
-
- access to the env files defined in the global config and in the `.env` file in the app directory.
8
-
9
-
This sandbox protects the host system from malicious code, and ensures that apps can only access the resources they need.
10
-
11
-
## Sharing files between apps
12
-
13
-
To share files between your apps, just use symbolic links!
14
-
15
-
For example, if you have two apps `app1` and `app2`, and you want `app2` to have access to the files in the `data` directory of `app1`, you can create a symbolic link in the `app2` directory:
16
-
17
-
```sh
18
-
ln -s $HOME/smallweb/app1/data $HOME/smallweb/app2/data
19
-
```
20
-
21
-
Linking files outside the smallweb directory also work, but it causes issues when syncing the files between different machines, so you should only use it if you only want to edit your files on one machine.
-126
docs/src/guides/server.md
-126
docs/src/guides/server.md
···
1
-
# Hosting Websites
2
-
3
-
Smallweb can also host dynamic websites. To create a dynamic website, you need to create a folder with a `main.[js,ts,jsx,tsx]` file in it.
4
-
5
-
The file should export a default object with a `fetch` method that takes a `Request` object as argument, and returns a `Response` object.
6
-
7
-
```ts
8
-
// File: ~/smallweb/example-server/main.ts
9
-
10
-
export default {
11
-
fetch(request: Request) {
12
-
const url = new URL(request.url);
13
-
const name = url.searchParams.get("name") || "world";
14
-
15
-
return new Response(`Hello, ${name}!`, {
16
-
headers: {
17
-
"Content-Type": "text/plain",
18
-
},
19
-
});
20
-
},
21
-
}
22
-
```
23
-
24
-
To access the server, open `https://example-server.localhost` in your browser.
25
-
26
-
## Using JSX
27
-
28
-
You can use the `@jsxImportSource` pragma to define the source of the jsx factory function. This allows you to use jsx in your server code.
29
-
30
-
```tsx
31
-
// File: ~/smallweb/jsx-example/main.tsx
32
-
/** @jsxImportSource npm:@preact **/
33
-
import render from "npm:preact-render-to-string";
34
-
35
-
const requestHandler = () => new Response(render(<h1>Hello, world!</h1>), {
36
-
headers: {
37
-
"Content-Type": "text/html",
38
-
},
39
-
});
40
-
41
-
export default { fetch: requestHandler };
42
-
```
43
-
44
-
To access the server, open `https://jsx-example.localhost` in your browser.
45
-
46
-
## Routing Requests using Hono
47
-
48
-
Smallweb use the [deno](https://deno.com) runtime to evaluate the server code. You get typescript and jsx support out of the box, and you can import any module from the npm and jsr registry by prefixing the module name with `npm:` or `jsr:`.
49
-
50
-
As an example, the following code snippet use the `@hono/hono` extract params from the request url.
51
-
52
-
```jsx
53
-
// File: ~/smallweb/hono-example/main.ts
54
-
55
-
import { Hono } from "jsr:@hono/hono";
56
-
57
-
const app = new Hono();
58
-
59
-
app.get("/", c => c.text("Hello, world!"));
60
-
61
-
app.get("/:name", c => c.text(`Hello, ${c.params.name}!`));
62
-
63
-
// Hono instances have a `fetch`, so they can be used as the default export
64
-
export default app;
65
-
```
66
-
67
-
To access the server, open `https://hono-example.localhost` in your browser.
68
-
69
-
## Static Websites
70
-
71
-
If your smallweb does not contains a `main.[js,ts,jsx,tsx]` file, Smallweb will serve the folder as a static website.
72
-
73
-
You can create a website by just adding an `index.html` file in the folder.
74
-
75
-
```html
76
-
<!-- File: ~/smallweb/example-static/index.html -->
77
-
<!DOCTYPE html>
78
-
<html>
79
-
<head>
80
-
<title>Example Static Website</title>
81
-
</head>
82
-
<body>
83
-
<h1>Hello, world!</h1>
84
-
</body>
85
-
</html>
86
-
```
87
-
88
-
To access the website, open `https://example-static.localhost` in your browser.
89
-
90
-
The static server also supports transpiling `.ts`, `.tsx`, `.jsx`, meaning that you can just import them from your static website.
91
-
92
-
```html
93
-
<!-- ~/smallweb/example-static/index.html -->
94
-
<!DOCTYPE html>
95
-
<html>
96
-
<head>
97
-
<title>Example Static Website</title>
98
-
</head>
99
-
<body>
100
-
<div id="root"></div>
101
-
<script src="script.tsx"></script>
102
-
</body>
103
-
```
104
-
105
-
You'll need to add a pragma to the script file to tell smallweb how to transpile it.
106
-
107
-
```tsx
108
-
// ~/smallweb/example-static/script.tsx
109
-
/** @jsxImportSource https://esm.sh/react **/
110
-
import { render } from "react-dom";
111
-
112
-
render(<h1>Hello, world!</h1>, document.getElementById("root"));
113
-
```
114
-
115
-
Only use imports that are usable from the browser. `jsr:` and `npm:` specifiers are not supported in the browser.
116
-
117
-
If your static website contains a `main.js` file, but you want to serve it as a static website, you can do the following:
118
-
119
-
- rename it to something else
120
-
- create a smallweb.json with the following content:
121
-
122
-
```json
123
-
{
124
-
"entrypoint": "smallweb:static"
125
-
}
126
-
```
docs/src/hosting/cloudflare/apex.png
docs/src/hosting/cloudflare/apex.png
This is a binary file and will not be displayed.
-73
docs/src/hosting/cloudflare/cloudflare.md
-73
docs/src/hosting/cloudflare/cloudflare.md
···
1
-
Cloudflare Tunnel is a **free** service that allows you to expose your local server to the internet, without having to expose your local IP address.
2
-
3
-
Additionally, it provides some protection against DDoS attacks, and allows you to use Cloudflare's other services like Access.
4
-
5
-
## Setup
6
-
7
-
1. Make sure that you have a domain name that you can manage with Cloudflare.
8
-
9
-
1. Install smallweb on your server, and register it as a service.
10
-
11
-
```ts
12
-
// install deno
13
-
curl -fsSL https://deno.land/install.sh | sh
14
-
15
-
// install smallweb
16
-
curl -sSfL https://install.smallweb.run | sh
17
-
18
-
// register smallweb as a service
19
-
smallweb service install
20
-
21
-
// make sure that the server service is running
22
-
smallweb service status
23
-
```
24
-
25
-
1. Set the `domain` field in your smallweb config to your domain name.
26
-
27
-
```sh
28
-
# open the smallweb config in your default editor
29
-
smallweb config
30
-
```
31
-
32
-
1. From your cloudflare dashboard, navigate to `Zero Trust > Networks > Tunnels`
33
-
34
-
1. Click on `Create a tunnel`, and select the `Clouflared` option
35
-
36
-
1. Follow the intructions to install cloudflared, and create a connector on your device.
37
-
38
-
1. Add a wildcard hostname for your tunnel (ex: `*.<your-domain>`), and use `http://localhost:7777` as the origin service.
39
-
40
-
41
-
42
-
1. Do the same for your apex domain, if you want to manage it using smallweb.
43
-
44
-
1. Copy the tunnel ID, and go to `Websites > DNS > Records`.
45
-
46
-
1. Add a new `CNAME` record for your wildcard hostname, with a target of `<tunnel-id>.cfargotunnel.com`.
47
-
48
-
49
-
50
-
## Checking that your tunnel is running
51
-
52
-
Create a dummy smallweb app in `~/smallweb/example`
53
-
54
-
```sh
55
-
mkdir -p ~/smallweb/example
56
-
CAT <<EOF > ~/smallweb/example/main.ts
57
-
export default {
58
-
fetch() {
59
-
return new Response("Smallweb is running", {
60
-
headers: {
61
-
"Content-Type": "text/plain",
62
-
},
63
-
});
64
-
}
65
-
}
66
-
EOF
67
-
```
68
-
69
-
If everything went well, you should be able to access `https://example.<your-domain>` in your browser, and see the message `Smallweb is running`.
70
-
71
-
## Optional Steps
72
-
73
-
- You can protect your tunnel (or specific apps) with Cloudflare Access.
docs/src/hosting/cloudflare/dns.png
docs/src/hosting/cloudflare/dns.png
This is a binary file and will not be displayed.
docs/src/hosting/cloudflare/tunnel.png
docs/src/hosting/cloudflare/tunnel.png
This is a binary file and will not be displayed.
-17
docs/src/hosting/deno-deploy.md
-17
docs/src/hosting/deno-deploy.md
···
1
-
# Deno Deploy
2
-
3
-
If one of your websites is starting to get a lot of traffic, you might want to deploy it to a cloud provider.
4
-
5
-
Deno Deploy is a cloud platform that allows you to deploy your Deno apps with ease. It's a great choice for smallweb apps, since it's built on top of Deno, and it's very easy to use.
6
-
7
-
To deploy an app, you'll just need to:
8
-
9
-
1. Install the `deployctl` cli:
10
-
11
-
```sh
12
-
deno install -Arf jsr:@deno/deployctl
13
-
```
14
-
15
-
2. Run `deployctl deploy`, and follow the instructions.
16
-
17
-
Beware, all Deno APIs are not available in Deno Deploy. For example, you won't be able to write files to the filesystem.
docs/src/hosting/localhost/architecture.excalidraw.png
docs/src/hosting/localhost/architecture.excalidraw.png
This is a binary file and will not be displayed.
-213
docs/src/hosting/localhost/localhost.md
-213
docs/src/hosting/localhost/localhost.md
···
1
-
This page will guide you through the process of setting up your local environment for smallweb on MacOS.
2
-
3
-
This setup is useful for developing and testing smallweb apps locally, without having to deploy them to the internet.
4
-
5
-
If you want to expose your apps to the internet instead, you can follow the [Cloudflare Tunnel setup guide](../cloudflare/cloudflare.md).
6
-
7
-
## Architecture
8
-
9
-
The following diagram illustrates the architecture of the local setup:
10
-
11
-
12
-
13
-
The components needed are:
14
-
15
-
- a dns server to map `*.localhost` domains to `127.0.0.1` ip address (dnsmasq)
16
-
- a reverse proxy to automatically generate https certificates for each domain, and redirect traffic to the smallweb evaluation server (caddy)
17
-
- a service to map each domain to the corresponding folder in ~/smallweb, and spawn a deno subprocess for each request (smallweb)
18
-
19
-
## MacOS setup
20
-
21
-
In the future, we might provide a script to automate this process, but for now, it's a manual process.
22
-
23
-
### Install Brew
24
-
25
-
```sh
26
-
# install homebrew (if not already installed)
27
-
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
28
-
```
29
-
30
-
### Install Deno {#install-deno-macos}
31
-
32
-
```sh
33
-
brew install deno
34
-
```
35
-
36
-
### Setup Smallweb {#setup-smallweb-macos}
37
-
38
-
```sh
39
-
brew install pomdtr/tap/smallweb
40
-
smallweb service install
41
-
```
42
-
43
-
### Setup Caddy {#setup-caddy-macos}
44
-
45
-
Caddy’s configuration path depends on whether you're using an Intel-based Mac or an Apple Silicon (M1/M2) Mac.
46
-
47
-
- **For Apple Silicon (M1/M2) Macs**:
48
-
The default installation path is `/opt/homebrew/etc/Caddyfile`.
49
-
- **For Intel-based Macs**:
50
-
The default installation path is `/usr/local/etc/Caddyfile`.
51
-
52
-
#### Apple Silicon (M1/M2):
53
-
54
-
```sh
55
-
brew install caddy
56
-
57
-
# Write caddy configuration
58
-
cat <<EOF > /opt/homebrew/etc/Caddyfile
59
-
localhost, *.localhost, *.*.localhost {
60
-
tls internal {
61
-
on_demand
62
-
}
63
-
64
-
reverse_proxy localhost:7777
65
-
}
66
-
EOF
67
-
```
68
-
69
-
#### Intel-based:
70
-
71
-
```sh
72
-
brew install caddy
73
-
74
-
# Write caddy configuration
75
-
cat <<EOF > /usr/local/etc/Caddyfile
76
-
localhost, *.localhost, *.*.localhost {
77
-
tls internal {
78
-
on_demand
79
-
}
80
-
81
-
reverse_proxy localhost:7777
82
-
}
83
-
EOF
84
-
```
85
-
86
-
#### Run Caddy:
87
-
88
-
```sh
89
-
# Run caddy in the background
90
-
brew services start caddy
91
-
92
-
# Add caddy https certificates to your keychain
93
-
caddy trust
94
-
```
95
-
96
-
### Setup dnsmasq {#setup-dnsmasq-macos}
97
-
98
-
The configuration path for dnsmasq also depends on your Mac's architecture.
99
-
100
-
#### Apple Silicon (M1/M2):
101
-
102
-
```sh
103
-
brew install dnsmasq
104
-
105
-
# Write dnsmasq configuration
106
-
echo "address=/.localhost/127.0.0.1" >> /opt/homebrew/etc/dnsmasq.conf
107
-
```
108
-
109
-
#### Intel-based:
110
-
111
-
```sh
112
-
brew install dnsmasq
113
-
114
-
# Write dnsmasq configuration
115
-
echo "address=/.localhost/127.0.0.1" >> /usr/local/etc/dnsmasq.conf
116
-
```
117
-
118
-
#### Run dnsmasq:
119
-
120
-
```sh
121
-
# Run dnsmasq in the background
122
-
sudo brew services start dnsmasq
123
-
124
-
# Indicates to the system to use dnsmasq for .localhost domains
125
-
sudo mkdir -p /etc/resolver
126
-
cat <<EOF | sudo tee -a /etc/resolver/localhost
127
-
nameserver 127.0.0.1
128
-
EOF
129
-
```
130
-
131
-
## Testing the setup {#testing-the-setup-macos}
132
-
133
-
First, let's create a dummy smallweb website:
134
-
135
-
```sh
136
-
mkdir -p ~/smallweb/example
137
-
cat <<EOF > ~/smallweb/example/main.ts
138
-
export default {
139
-
fetch() {
140
-
return new Response("Smallweb is running", {
141
-
headers: {
142
-
"Content-Type": "text/plain",
143
-
},
144
-
});
145
-
}
146
-
}
147
-
EOF
148
-
```
149
-
150
-
If everything went well, you should be able to access `https://example.localhost` in your browser, and see the message `Smallweb is running`.
151
-
152
-
## Ubuntu / Debian setup
153
-
154
-
### Install Deno {#install-deno-ubuntu}
155
-
156
-
```sh
157
-
curl -fsSL https://deno.land/install.sh | sh
158
-
# add ~/.deno/bin to PATH
159
-
echo "export PATH=\$PATH:\$HOME/.deno/bin" >> ~/.bashrc
160
-
```
161
-
162
-
### Setup Smallweb {#setup-smallweb-ubuntu}
163
-
164
-
```sh
165
-
curl -fsSL https://install.smallweb.run | sh
166
-
# add ~/.local/bin to PATH
167
-
echo "export PATH=\$PATH:\$HOME/.local/bin" >> ~/.bashrc
168
-
smallweb service install
169
-
```
170
-
171
-
### Setup Caddy {#setup-caddy-ubuntu}
172
-
173
-
```sh
174
-
sudo apt install -y caddy
175
-
176
-
# Write caddy configuration
177
-
cat <<EOF > /etc/caddy/Caddyfile
178
-
*.localhost {
179
-
tls internal {
180
-
on_demand
181
-
}
182
-
183
-
reverse_proxy localhost:7777
184
-
}
185
-
EOF
186
-
187
-
sudo systemctl restart caddy
188
-
189
-
caddy trust
190
-
```
191
-
192
-
There is no need to setup dnsmasq on Ubuntu, as it seems to be already configured to resolve `.localhost` domains to `127.0.0.1`.
193
-
194
-
### Testing the setup {#testing-setup-ubuntu}
195
-
196
-
First, let's create a dummy smallweb website:
197
-
198
-
```sh
199
-
mkdir -p ~/smallweb/example
200
-
CAT <<EOF > ~/smallweb/example/main.ts
201
-
export default {
202
-
fetch() {
203
-
return new Response("Smallweb is running", {
204
-
headers: {
205
-
"Content-Type": "text/plain",
206
-
},
207
-
});
208
-
}
209
-
}
210
-
EOF
211
-
```
212
-
213
-
If everything went well, you should be able to access `https://example.localhost` in your browser, and see the message `Smallweb is running`.
-60
docs/src/hosting/vps.md
-60
docs/src/hosting/vps.md
···
1
-
# VPS / Home Server
2
-
3
-
If you're using a Debian-based Server, you can follow these steps to setup smallweb, assuming you're logged in as root.
4
-
5
-
These steps will also work on other distributions, but you may need to adjust the package manager commands.
6
-
7
-
```bash
8
-
# create user with homedir and default shell
9
-
useradd --system --user-group --create-home --shell $(which bash) smallweb
10
-
11
-
# set a password for the smallweb user
12
-
passwd smallweb
13
-
14
-
# give the user sudo access (optional)
15
-
usermod -aG sudo smallweb
16
-
17
-
# allow the user to use systemd
18
-
usermod -aG systemd-journal smallweb
19
-
20
-
# run user services on login
21
-
loginctl enable-linger smallweb
22
-
```
23
-
24
-
At this point, you can switch to the `smallweb` user (ex: using `ssh smallweb@<ip>`) and install smallweb:
25
-
26
-
```bash
27
-
# install unzip (required for deno)
28
-
sudo apt update && sudo apt install unzip
29
-
30
-
# install deno
31
-
curl -fsSL https://deno.land/install.sh | sh # install deno
32
-
33
-
# install smallweb
34
-
curl -sSfL https://install.smallweb.run | sh # install smallweb
35
-
36
-
# start the smallweb service
37
-
smallweb service install
38
-
```
39
-
40
-
To make your service accessible from the internet, you have multiple options:
41
-
42
-
- setup a reverse proxy on port 443 (I use caddy)
43
-
- using cloudflare tunnel (see [cloudflare setup](./cloudflare/cloudflare.md))
44
-
45
-
## Syncing files using mutagen
46
-
47
-
I recommend using [mutagen](https://mutagen.io) to sync your files between your development machine and the server.
48
-
49
-
First, install mutagen on your development machine, then enable the daemon using `mutagen daemon register`, and finally, run the following command to sync your files:
50
-
51
-
```bash
52
-
mutagen sync create --name=smallweb --ignore-vcs --ignore=node_modules \
53
-
~/smallweb smallweb@<server-ip>:/home/smallweb/smallweb
54
-
```
55
-
56
-
From now on, each time you make a change to your files, they will be automatically synced to the server, and vice versa.
57
-
58
-
Your git repository will only be present on one machine, you can choose if you want to keep it on your development machine or on the server. Syncing git repositories [is not recommended](https://mutagen.io/documentation/synchronization/version-control-systems).
59
-
60
-
I also prefer to skip syncing the `node_modules` folder, as deno automatically fetches them when needed.
-60
docs/src/reference/app_config.md
-60
docs/src/reference/app_config.md
···
1
-
# App Configuration Reference
2
-
3
-
The smallweb configuration can be defined in a `smallweb.json[c]` file at the root of the project. This config file is optional, and sensible defaults are used when it is not present.
4
-
5
-
## Available Fields
6
-
7
-
### `entrypoint`
8
-
9
-
The `entrypoint` field defines the file to serve. If this field is not provided, the app will look for a `main.[js,ts,jsx,tsx]` file in the root directory.
10
-
11
-
### `root`
12
-
13
-
The `root` field defines the root directory of the app. If this field is not provided, the app will use the app directory as the root directory.
14
-
15
-
### `private`
16
-
17
-
If the `private` field is set to `true`, the app will ask for your admin username and password before serving the app using basic auth.
18
-
19
-
### `privateRoutes`
20
-
21
-
If you only want to protect a subset of routes, you can use the `privateRoutes` field. This field is an array of routes that require authentication.
22
-
23
-
```json
24
-
{
25
-
"privateRoutes": [
26
-
"/private",
27
-
"/admin/*"
28
-
]
29
-
}
30
-
```
31
-
32
-
### `publicRoutes`
33
-
34
-
If you want to make a subset of routes public, you can use the `publicRoutes` field. This field is an array of routes that do not require authentication.
35
-
36
-
```json
37
-
{
38
-
"private": true,
39
-
"publicRoutes": [
40
-
"/public/*",
41
-
]
42
-
}
43
-
```
44
-
45
-
### `crons`
46
-
47
-
The `crons` field defines a list of cron jobs to run. See the [Cron Jobs](../guides/cron.md) guide for more information.
48
-
49
-
```json
50
-
{
51
-
"crons": [
52
-
{
53
-
"name": "daily-task", // The name of the cron task (required)
54
-
"description": "A daily task", // A description for the task (optional)
55
-
"schedule": "0 0 * * *", // a cron expression (required)
56
-
"args": [] // arguments to pass to the task (required)
57
-
}
58
-
]
59
-
}
60
-
```
-701
docs/src/reference/cli.md
-701
docs/src/reference/cli.md
···
1
-
# CLI Reference
2
-
3
-
## smallweb
4
-
5
-
Host websites from your internet folder
6
-
7
-
### Options
8
-
9
-
```
10
-
-h, --help help for smallweb
11
-
```
12
-
13
-
## smallweb api
14
-
15
-
Interact with the smallweb API
16
-
17
-
```
18
-
smallweb api [flags]
19
-
```
20
-
21
-
### Options
22
-
23
-
```
24
-
-d, --data string Data to send in the request body
25
-
-H, --header stringArray HTTP headers to use
26
-
-h, --help help for api
27
-
-X, --method string HTTP method to use (default "GET")
28
-
```
29
-
30
-
## smallweb capture
31
-
32
-
Extension capture
33
-
34
-
```
35
-
smallweb capture [flags]
36
-
```
37
-
38
-
### Options
39
-
40
-
```
41
-
-h, --help help for capture
42
-
```
43
-
44
-
## smallweb changelog
45
-
46
-
Show the changelog
47
-
48
-
```
49
-
smallweb changelog [flags]
50
-
```
51
-
52
-
### Options
53
-
54
-
```
55
-
-h, --help help for changelog
56
-
```
57
-
58
-
## smallweb clone
59
-
60
-
Clone an app
61
-
62
-
```
63
-
smallweb clone [app] [new-name] [flags]
64
-
```
65
-
66
-
### Options
67
-
68
-
```
69
-
-h, --help help for clone
70
-
```
71
-
72
-
## smallweb completion
73
-
74
-
Generate the autocompletion script for the specified shell
75
-
76
-
### Synopsis
77
-
78
-
Generate the autocompletion script for smallweb for the specified shell.
79
-
See each sub-command's help for details on how to use the generated script.
80
-
81
-
82
-
### Options
83
-
84
-
```
85
-
-h, --help help for completion
86
-
```
87
-
88
-
## smallweb completion bash
89
-
90
-
Generate the autocompletion script for bash
91
-
92
-
### Synopsis
93
-
94
-
Generate the autocompletion script for the bash shell.
95
-
96
-
This script depends on the 'bash-completion' package.
97
-
If it is not installed already, you can install it via your OS's package manager.
98
-
99
-
To load completions in your current shell session:
100
-
101
-
source <(smallweb completion bash)
102
-
103
-
To load completions for every new session, execute once:
104
-
105
-
#### Linux:
106
-
107
-
smallweb completion bash > /etc/bash_completion.d/smallweb
108
-
109
-
#### macOS:
110
-
111
-
smallweb completion bash > $(brew --prefix)/etc/bash_completion.d/smallweb
112
-
113
-
You will need to start a new shell for this setup to take effect.
114
-
115
-
116
-
```
117
-
smallweb completion bash
118
-
```
119
-
120
-
### Options
121
-
122
-
```
123
-
-h, --help help for bash
124
-
--no-descriptions disable completion descriptions
125
-
```
126
-
127
-
## smallweb completion fish
128
-
129
-
Generate the autocompletion script for fish
130
-
131
-
### Synopsis
132
-
133
-
Generate the autocompletion script for the fish shell.
134
-
135
-
To load completions in your current shell session:
136
-
137
-
smallweb completion fish | source
138
-
139
-
To load completions for every new session, execute once:
140
-
141
-
smallweb completion fish > ~/.config/fish/completions/smallweb.fish
142
-
143
-
You will need to start a new shell for this setup to take effect.
144
-
145
-
146
-
```
147
-
smallweb completion fish [flags]
148
-
```
149
-
150
-
### Options
151
-
152
-
```
153
-
-h, --help help for fish
154
-
--no-descriptions disable completion descriptions
155
-
```
156
-
157
-
## smallweb completion powershell
158
-
159
-
Generate the autocompletion script for powershell
160
-
161
-
### Synopsis
162
-
163
-
Generate the autocompletion script for powershell.
164
-
165
-
To load completions in your current shell session:
166
-
167
-
smallweb completion powershell | Out-String | Invoke-Expression
168
-
169
-
To load completions for every new session, add the output of the above command
170
-
to your powershell profile.
171
-
172
-
173
-
```
174
-
smallweb completion powershell [flags]
175
-
```
176
-
177
-
### Options
178
-
179
-
```
180
-
-h, --help help for powershell
181
-
--no-descriptions disable completion descriptions
182
-
```
183
-
184
-
## smallweb completion zsh
185
-
186
-
Generate the autocompletion script for zsh
187
-
188
-
### Synopsis
189
-
190
-
Generate the autocompletion script for the zsh shell.
191
-
192
-
If shell completion is not already enabled in your environment you will need
193
-
to enable it. You can execute the following once:
194
-
195
-
echo "autoload -U compinit; compinit" >> ~/.zshrc
196
-
197
-
To load completions in your current shell session:
198
-
199
-
source <(smallweb completion zsh)
200
-
201
-
To load completions for every new session, execute once:
202
-
203
-
#### Linux:
204
-
205
-
smallweb completion zsh > "${fpath[1]}/_smallweb"
206
-
207
-
#### macOS:
208
-
209
-
smallweb completion zsh > $(brew --prefix)/share/zsh/site-functions/_smallweb
210
-
211
-
You will need to start a new shell for this setup to take effect.
212
-
213
-
214
-
```
215
-
smallweb completion zsh [flags]
216
-
```
217
-
218
-
### Options
219
-
220
-
```
221
-
-h, --help help for zsh
222
-
--no-descriptions disable completion descriptions
223
-
```
224
-
225
-
## smallweb config
226
-
227
-
Open the smallweb config in your editor
228
-
229
-
```
230
-
smallweb config [key] [flags]
231
-
```
232
-
233
-
### Options
234
-
235
-
```
236
-
-h, --help help for config
237
-
```
238
-
239
-
## smallweb create
240
-
241
-
Create a new smallweb app
242
-
243
-
```
244
-
smallweb create <app> [flags]
245
-
```
246
-
247
-
### Options
248
-
249
-
```
250
-
-h, --help help for create
251
-
```
252
-
253
-
## smallweb cron
254
-
255
-
Manage cron jobs
256
-
257
-
### Options
258
-
259
-
```
260
-
-h, --help help for cron
261
-
```
262
-
263
-
## smallweb cron list
264
-
265
-
List cron jobs
266
-
267
-
```
268
-
smallweb cron list [flags]
269
-
```
270
-
271
-
### Options
272
-
273
-
```
274
-
--app string filter by app
275
-
-h, --help help for list
276
-
--json output as json
277
-
```
278
-
279
-
## smallweb cron trigger
280
-
281
-
Trigger a cron job
282
-
283
-
```
284
-
smallweb cron trigger <id> [flags]
285
-
```
286
-
287
-
### Options
288
-
289
-
```
290
-
-h, --help help for trigger
291
-
```
292
-
293
-
## smallweb delete
294
-
295
-
Delete an app
296
-
297
-
```
298
-
smallweb delete [flags]
299
-
```
300
-
301
-
### Options
302
-
303
-
```
304
-
-h, --help help for delete
305
-
```
306
-
307
-
## smallweb docs
308
-
309
-
Generate smallweb cli documentation
310
-
311
-
```
312
-
smallweb docs [flags]
313
-
```
314
-
315
-
### Options
316
-
317
-
```
318
-
-h, --help help for docs
319
-
```
320
-
321
-
## smallweb edit
322
-
323
-
Extension edit
324
-
325
-
```
326
-
smallweb edit [flags]
327
-
```
328
-
329
-
### Options
330
-
331
-
```
332
-
-h, --help help for edit
333
-
```
334
-
335
-
## smallweb gallery
336
-
337
-
Extension gallery
338
-
339
-
```
340
-
smallweb gallery [flags]
341
-
```
342
-
343
-
### Options
344
-
345
-
```
346
-
-h, --help help for gallery
347
-
```
348
-
349
-
## smallweb hello
350
-
351
-
Extension hello
352
-
353
-
```
354
-
smallweb hello [flags]
355
-
```
356
-
357
-
### Options
358
-
359
-
```
360
-
-h, --help help for hello
361
-
```
362
-
363
-
## smallweb list
364
-
365
-
List all smallweb apps
366
-
367
-
```
368
-
smallweb list [flags]
369
-
```
370
-
371
-
### Options
372
-
373
-
```
374
-
-h, --help help for list
375
-
--json output as json
376
-
```
377
-
378
-
## smallweb log
379
-
380
-
Show logs
381
-
382
-
### Options
383
-
384
-
```
385
-
-h, --help help for log
386
-
```
387
-
388
-
## smallweb log console
389
-
390
-
Show console logs
391
-
392
-
```
393
-
smallweb log console [flags]
394
-
```
395
-
396
-
### Options
397
-
398
-
```
399
-
--app string filter logs by app
400
-
-h, --help help for console
401
-
--json output logs in JSON format
402
-
```
403
-
404
-
## smallweb log cron
405
-
406
-
Show cron logs
407
-
408
-
```
409
-
smallweb log cron [flags]
410
-
```
411
-
412
-
### Options
413
-
414
-
```
415
-
-h, --help help for cron
416
-
--host string filter logs by host
417
-
--json output logs in JSON format
418
-
```
419
-
420
-
## smallweb log http
421
-
422
-
Show HTTP logs
423
-
424
-
```
425
-
smallweb log http [flags]
426
-
```
427
-
428
-
### Options
429
-
430
-
```
431
-
-h, --help help for http
432
-
--host string filter logs by host
433
-
--json output logs in JSON format
434
-
```
435
-
436
-
## smallweb open
437
-
438
-
Open an app in the browser
439
-
440
-
```
441
-
smallweb open [app] [flags]
442
-
```
443
-
444
-
### Options
445
-
446
-
```
447
-
-h, --help help for open
448
-
```
449
-
450
-
## smallweb rename
451
-
452
-
Rename an app
453
-
454
-
```
455
-
smallweb rename [app] [new-name] [flags]
456
-
```
457
-
458
-
### Options
459
-
460
-
```
461
-
-h, --help help for rename
462
-
```
463
-
464
-
## smallweb run
465
-
466
-
Run an app cli
467
-
468
-
```
469
-
smallweb run <app> [args...] [flags]
470
-
```
471
-
472
-
### Options
473
-
474
-
```
475
-
-h, --help help for run
476
-
```
477
-
478
-
## smallweb service
479
-
480
-
Manage smallweb service
481
-
482
-
### Options
483
-
484
-
```
485
-
-h, --help help for service
486
-
```
487
-
488
-
## smallweb service install
489
-
490
-
Install smallweb as a service
491
-
492
-
```
493
-
smallweb service install [flags]
494
-
```
495
-
496
-
### Options
497
-
498
-
```
499
-
-h, --help help for install
500
-
```
501
-
502
-
## smallweb service logs
503
-
504
-
Print service logs
505
-
506
-
```
507
-
smallweb service logs [flags]
508
-
```
509
-
510
-
### Options
511
-
512
-
```
513
-
-f, --follow Follow log output
514
-
-h, --help help for logs
515
-
```
516
-
517
-
## smallweb service restart
518
-
519
-
Restart smallweb service
520
-
521
-
```
522
-
smallweb service restart [flags]
523
-
```
524
-
525
-
### Options
526
-
527
-
```
528
-
-h, --help help for restart
529
-
```
530
-
531
-
## smallweb service start
532
-
533
-
Start smallweb service
534
-
535
-
```
536
-
smallweb service start [flags]
537
-
```
538
-
539
-
### Options
540
-
541
-
```
542
-
-h, --help help for start
543
-
```
544
-
545
-
## smallweb service status
546
-
547
-
View service status
548
-
549
-
```
550
-
smallweb service status [flags]
551
-
```
552
-
553
-
### Options
554
-
555
-
```
556
-
-h, --help help for status
557
-
```
558
-
559
-
## smallweb service stop
560
-
561
-
Stop smallweb service
562
-
563
-
```
564
-
smallweb service stop [flags]
565
-
```
566
-
567
-
### Options
568
-
569
-
```
570
-
-h, --help help for stop
571
-
```
572
-
573
-
## smallweb service uninstall
574
-
575
-
Uninstall smallweb service
576
-
577
-
```
578
-
smallweb service uninstall [flags]
579
-
```
580
-
581
-
### Options
582
-
583
-
```
584
-
-h, --help help for uninstall
585
-
```
586
-
587
-
## smallweb token
588
-
589
-
Manage api tokens
590
-
591
-
### Options
592
-
593
-
```
594
-
-h, --help help for token
595
-
```
596
-
597
-
## smallweb token create
598
-
599
-
Create a new token
600
-
601
-
```
602
-
smallweb token create [flags]
603
-
```
604
-
605
-
### Options
606
-
607
-
```
608
-
--admin admin token
609
-
-a, --app strings app token
610
-
-d, --description string description of the token
611
-
-h, --help help for create
612
-
```
613
-
614
-
## smallweb token delete
615
-
616
-
Remove a token
617
-
618
-
```
619
-
smallweb token delete <id> [flags]
620
-
```
621
-
622
-
### Options
623
-
624
-
```
625
-
-h, --help help for delete
626
-
```
627
-
628
-
## smallweb token list
629
-
630
-
List all tokens
631
-
632
-
```
633
-
smallweb token list [flags]
634
-
```
635
-
636
-
### Options
637
-
638
-
```
639
-
-h, --help help for list
640
-
-j, --json output as JSON
641
-
```
642
-
643
-
## smallweb tunnel
644
-
645
-
Start a tunnel to a remote server (powered by localhost.run)
646
-
647
-
```
648
-
smallweb tunnel [flags]
649
-
```
650
-
651
-
### Options
652
-
653
-
```
654
-
-h, --help help for tunnel
655
-
```
656
-
657
-
## smallweb up
658
-
659
-
Start the smallweb evaluation server
660
-
661
-
```
662
-
smallweb up [flags]
663
-
```
664
-
665
-
### Options
666
-
667
-
```
668
-
-h, --help help for up
669
-
```
670
-
671
-
## smallweb upgrade
672
-
673
-
Upgrade to the latest version
674
-
675
-
```
676
-
smallweb upgrade [version] [flags]
677
-
```
678
-
679
-
### Options
680
-
681
-
```
682
-
-h, --help help for upgrade
683
-
```
684
-
685
-
## smallweb view
686
-
687
-
Extension view
688
-
689
-
```
690
-
smallweb view [flags]
691
-
```
692
-
693
-
### Options
694
-
695
-
```
696
-
-h, --help help for view
697
-
```
698
-
699
-
700
-
701
-
<!-- markdownlint-disable-file -->
-113
docs/src/reference/global_config.md
-113
docs/src/reference/global_config.md
···
1
-
# Global Config
2
-
3
-
The smallweb config is located at `~/.config/smallweb/config.json[c]`. It is a json file that defines global settings for smallweb.
4
-
5
-
You can also specify a custom config file by setting the `SMALLWEB_CONFIG` environment variable.
6
-
7
-
Smallweb also respects the `XDG_CONFIG_HOME` environment variable.
8
-
9
-
## Available Fields
10
-
11
-
### `addr`
12
-
13
-
The `addr` field defines the addr to bind to. By default, it is `:7777`.
14
-
15
-
```json
16
-
{
17
-
"addr": "127.0.0.1:8000"
18
-
}
19
-
```
20
-
21
-
If you want to use an unix socket, you can use the `unix/` prefix.
22
-
23
-
```json
24
-
{
25
-
"addr": "unix/~/smallweb.sock"
26
-
}
27
-
```
28
-
29
-
### `cert` and `key`
30
-
31
-
The `cert` and `key` fields define the path to the SSL certificate and key.
32
-
33
-
```json
34
-
{
35
-
"cert": "~/cert.pem",
36
-
"key": "~/key.pem"
37
-
}
38
-
```
39
-
40
-
### `domain`
41
-
42
-
The `domain` field defines the apex domain used for routing.
43
-
44
-
```json
45
-
{
46
-
"domain": "example.com"
47
-
}
48
-
```
49
-
50
-
See the [Routing](../guides/routing.md) guide for more information.
51
-
52
-
### `dir`
53
-
54
-
The `dir` field defines the root directory for all apps.
55
-
56
-
```json
57
-
{
58
-
"dir": "~/smallweb"
59
-
}
60
-
```
61
-
62
-
### `email`
63
-
64
-
The `email` field is required to enable lastlogin authentication for private apps.
65
-
66
-
If it is not set, private will show a basic auth prompt instead.
67
-
68
-
```json
69
-
{
70
-
"email": "pomdtr@example.com"
71
-
}
72
-
```
73
-
74
-
### `customDomains`
75
-
76
-
The `customDomains` field is an object that maps custom domains to apps.
77
-
78
-
```json
79
-
{
80
-
"customDomains": {
81
-
"example.com": "example",
82
-
}
83
-
}
84
-
```
85
-
86
-
## Default Config
87
-
88
-
By default the config file looks like this:
89
-
90
-
```json
91
-
{
92
-
"addr": ":7777",
93
-
"dir": "~/smallweb",
94
-
}
95
-
```
96
-
97
-
Since smallweb requires a domain to be set, the minimal config is:
98
-
99
-
```json
100
-
{
101
-
"domain": "example.com"
102
-
}
103
-
```
104
-
105
-
which is equivalent to:
106
-
107
-
```json
108
-
{
109
-
"domain": "example.com",
110
-
"addr": ":7777",
111
-
"dir": "~/smallweb",
112
-
}
113
-
```