Smallweb 0.25
by Achille Lacoin
4 min read
Smallweb 0.25 is out! It includes a includes two really powerful features: pluggable authentication, and support for receiving emails. Let's get into it!
OpenID Connect Support
Smallweb now supports OpenID Connect! This means that you can use any OpenID Connect provider to authenticate your users. This includes popular providers like Google, GitHub, and Microsoft.
The easier way to test this out is to use the https://lastlogin.net provider. Just add the oidc.issuer key to your smallweb config, and whitelist your own email:
{
"domain": "example.com",
"oidc.issuer": "https://lastlogin.net",
// emails in this list will be able to access all private apps
"authorizedEmails": [
"[email protected]"
],
"apps": {
"dashboard": {
// all routes in this app will require authentication
"private": true,
// emails in this list will only be able to access this app
"authorizedEmails": [
"[email protected]"
]
}
}
}
The next time you go to https://dashboard.example.com, you will be redirected to the provider authorization page. After you log in (as one of the authorized emails), you will be redirected back to your app.
You can access the user information using the Remote-* headers.
export default {
fetch: (req: Request) => {
const email = req.headers.get("Remote-Email");
return new Response(`Hello ${email}!`);
}
}
The coolest part is that you can host your own OpenID Connect provider in smallweb thanks to a library like OpenAuth.
New email endpoint
You can now send email to smallweb apps ! Just start smallweb with the --smtp-addr flag:
smallweb up --smtp-addr :25
You'll then need to set a few records in your DNS, and your app will be accessible at <app>@<domain>.
To handle incoming emails, just declare a email entrypoint in your app:
import PostalMime from "npm:postal-mime";
export default {
email: (msg: ReadableStream) => {
const email = await PostalMime.parse(msg);
console.log('Subject:', email.subject);
console.log('HTML:', email.html);
console.log('Text:', email.text);
}
}
As you can see, smallweb does not parse the email content for you. As there is no web-standard Email object, I prefer to leverage external libraries. I had a good experience using postal-mime.
SSH keys support in .sops.yaml
You can now public ssh public keys in your .sops.yaml file (instead of age public keys).
# $SMALLWEB_DIR/.sops.yaml
creation_rules:
- key_groups:
- age:
- ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJW+GQk0KCvSreL+y3AZdtCu82+13E2eEled+sGRkIEv # laptop
- ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHpF8kTXaBHTZqKfmEsKTILSxQYpPenI7wyMK0qTNE8y # vps
More information in the docs.
Process stdin from the run entrypoint
You can now access input piped an app cli by using the input parameter in your run entrypoint. For example, here is a simple app that will prettify json passed through stdin:
// ~/smallweb/prettify/main.ts
import { toJson } from "jsr:@std/streams"
export default {
run: async (_args: string[], input: ReadableStream) => {
const json = await toJson(input);
console.log(JSON.stringify(json, null, 2));
}
}
Here is how it can be invoked:
cat example.json | smallweb run prettify
It also works when accessible app clis through ssh:
cat example.json | ssh [email protected]
Cron tasks are moved to the global config
Instead of declaring cron tasks in the app config:
// ~/smallweb/my-app/smallweb.json
{
"crons": [
{
"schedule": "@hourly",
"args": ["refresh"]
}
]
}
Crons are now specified from the global config:
// ~/smallweb/.smallweb/config.json
{
"apps": {
"my-app": {
"crons": [
{
"schedule": "@hourly",
"args": ["refresh"]
}
]
}
}
}
Reworked docker image
I've spent a lot of time working on the docker image to simplify using smallweb from your homelab. Here is a minimal example of a compose setup:
services:
smallweb:
image: ghcr.io/pomdtr/smallweb:latest
restart: unless-stopped
command: up --enable-crons --ssh-addr :2222
ports:
- 7777:7777
- 2222:2222
environment:
- PUID=1000
- PGID=1000
volumes:
- $HOME/smallweb:/smallweb
- $HOME/.ssh/id_ed25519:/home/smallweb/.ssh/id_ed25519
- deno_cache:/home/smallweb/.cache/deno
volumes:
deno_cache:
Json logs on stdout
In addition to the opentelemetry support released in 0.24, a lot of you have been asking for a simple way to get access to the http / console logs of your smallweb app.
The smallweb up command will now dump these logs using json to stdout.
$ smallweb up
{"time":"2025-03-27T16:01:24.100825+01:00","level":"INFO","msg":"serving http","domain":"smallweb.localhost","dir":"/Users/pomdtr/Developer/pomdtr/smallweb/example"}
{"time":"2025-03-27T16:01:30.524557+01:00","level":"INFO","msg":"<-- GET /.well-known/oauth-authorization-server","logger":"console","app":"auth","stream":"stdout"}
{"time":"2025-03-27T16:01:30.525509+01:00","level":"INFO","msg":"--> GET /.well-known/oauth-authorization-server \u001b[32m200\u001b[0m 1ms","logger":"console","app":"auth","stream":"stdout"}
{"time":"2025-03-27T16:01:30.526423+01:00","level":"INFO","msg":"200: OK","logger":"http","request":{"time":"2025-03-27T15:01:30.215387Z","method":"GET","host":"auth.smallweb.localhost","path":"/.well-known/openid-configuration","query":"","ip":"[::1]:51965","referer":"","length":0},"response":{"time":"2025-03-27T15:01:30.526409Z","latency":311019625,"status":200,"length":256},"id":"00cf33b0-a1e2-4dea-98dd-26bd6e78b237"}
{"time":"2025-03-27T16:01:30.564595+01:00","level":"INFO","msg":"200: OK","logger":"http","request":{"time":"2025-03-27T15:01:30.196483Z","method":"GET","host":"hono.smallweb.localhost","path":"/","query":"","ip":"[::1]:51963","referer":"","length":0},"response":{"time":"2025-03-27T15:01:30.564581Z","latency":368094708,"status":200,"length":5},"id":"30cbd0c1-67ad-45a7-b124-1fe2fff7ecfd"}
You can then get these logs from journalctl or docker logs, and use tools like jq
to process them.