Simplifying the initial setup experience

[markshuttle]

Hello. Before I open a PR I thought it would be best to have a discussion here about making the initial install and setup experience simpler. In general I think making software easier to install and run increases the pool of people who can contribute or advocate for that software. I'm no longer an active coder unless you count spreadsheets as software :) but I do often contribute to usability discussions in order to make open source reach a wider audience.

The branch which implements these ideas is at https://github.com/markshuttle/tuwunel if you want to try it out.

Last week, for a holiday project, I wanted to play with an OpenClaw-style AI assistant, and I wanted to setup a secure communication channel for it. We use Matrix for the Ubuntu community, but I have heard that Synapse is a little tricky, so I decided to try out Tuwunel. I chose PicoClaw (a very small claw-style AI assistant in Golang for devices like the Sipeed RISC-V SBCs). I also wanted to play with ACME certs and reverse proxies, and also try out Antigravity and Gemini.

All of these pieces work, and the steps to get it up and running are fine for expert open source people. But we could make it much easier!

For Tuwunel, I wanted to try making a snap package so it can be a one-command install for any distro that has snapd (Ubuntu and a few others by default, Debian and a few others as an option). This was quite easy (you can see it in snap./snapcraft.yaml in the branch I linked to above). However, I thought it would also be nice to offer an onboarding utility which initialises the service with a working, minimal config.

I don't know Rust but I thought the requirements could be stated clearly enough that it would be a good project to test out Gemini and Antigravity.

The result of that is an 'init' utility, also in that branch. I asked Gemini to keep dependencies to a minimum, so it's pretty basic. Nevertheless it provides a nice initial setup experience, asking the user for key information, writing out a basic minimal but working config, after which the daemon just runs.

With these two pieces of work, the install experience becomes:

sudo snap install tuwunel
sudo tuwunel.init

After that the daemon should be running, listening to the usual port.

Here is an example run:

$ sudo snap install --dangerous ./tuwunel_0+git.9d428f44_amd64.snap
tuwunel 0+git.9d428f44 installed

$ sudo tuwunel.init 
Tuwunel initialization.
We will create a minimal configuration file for your matrix server.

> Server name (e.g., matrix.example.com): matrix.test.it
> Registration token: ********
Registration token entropy: Excellent
> Would you like to create an initial admin user? [Yes/No/Quit]: Yes
> Admin username (without domain portion, eg. 'tom'): tom
> Admin password: ********
Admin password security: Excellent

Configuration file successfully written to /var/snap/tuwunel/common/tuwunel.toml
Initializing database and to create the first administrator...
2026-04-07T15:32:30.255091Z  WARN tuwunel_core::config::check: Configuration item `listening` is set to `false`. Cannot hear anyone.
2026-04-07T15:32:30.267386Z  INFO tuwunel::server: 1.6.0-rc-15 (9d428f449d-dirty) server_name=matrix.test.it database_path="/var/snap/tuwunel/common/db" log_levels=info
2026-04-07T15:32:30.465745Z  INFO main:start:open: tuwunel_database::engine::open: Opened database. columns=109 sequence=0 time=154.985515ms
2026-04-07T15:32:30.548041Z  WARN main:start: tuwunel_service::oauth::server: OIDC server (next-gen auth) requires `well_known.client` and one or more `identity_provider` to be configured
2026-04-07T15:32:30.573729Z  WARN main:start: tuwunel_service::migrations: Created new RocksDB database with version 17
2026-04-07T15:32:30.749541Z  WARN main:run:admin:command:full_register{username=None user_id=Some("@tom:matrix.test.it") origin=None is_appservice=false is_guest=false grant_first_user_admin=true displayname=None omit_displayname_suffix=false}: tuwunel_service::users::register: Granting @tom:matrix.test.it admin privileges as the first user
2026-04-07T15:32:30.751748Z  INFO main:run: tuwunel_service::admin::execute: Execute command #0 completed:
| level | span | message |
| ------: | :-----: | :------- |
|  WARN | full_register | Granting @tom:matrix.test.it admin privileges as the first user |

Created user with user_id: @tom:matrix.test.it and password: `tuwunel_0+git.638f3c03-dirty_amd64.snap`
2026-04-07T15:32:30.754604Z  WARN main:run:admin:command: tuwunel_admin::server::commands: shutdown command
2026-04-07T15:32:30.754663Z  INFO main:run: tuwunel_service::admin::execute: Execute command #1 completed:
| level | span | message |
| ------: | :-----: | :------- |
|  WARN |   command    | shutdown command |

Shutting down server...
2026-04-07T15:32:30.754776Z  INFO main:stop: tuwunel_service::services: Shutting down services...
2026-04-07T15:32:30.754924Z  INFO main:stop: tuwunel_router::run: Shutdown complete.

Initialization Complete! 🎉
The daemon can now be started, or will start automatically if you installed the Tuwunel snap.
It will by default listen only on 127.0.0.1:8008, you will probably want to direct traffic
there by reverse proxy. See the docs for more information.

You can sign into the server at:

  Homeserver URL: https://matrix.test.it
  Username: @tom:matrix.test.it
  Password: <the password you provided>

After this I verified the server was running on localhost:8008.

If you want to play with this you can build the snap yourself easily enough from the branch I linked above. I can also attach an x86 build of the snap to this. I would say "don't run binaries from random strangers on the internet" and suggest you install it in a VM.

If you build it yourself, or if you use the build I can provide, then you need to use --dangerous on the snap install (which is basically "--unsigned"). If this change is accepted upstream, then I would get some of my colleagues to help the community setup automatic build and publication of this snap for x86, arm, risc-v, power and mainframe (z) architectures. Ideally this would means someone could play with a nightly build as easily as:

  sudo snap switch tuwunel --channel=edge/nightly
  sudo snap refresh

Again, that sort of thing can really help accelerate participation and contribution because it becomes much easier for people to try the latest builds and provide feedback.

I'm going to apologise in advance for the fact that all the Rust in that init command is Gemini, though I would say I eyeballed it and tested it I am not a Rust developer at all so consider this more a proof of concept of the UX than a ready-to-merge code contribution.

To go further, I would like to work with people around Caddy and Lego to make the whole end to end experience of getting Matrix up and running, with Let's Encrypt certs, easy for less technical people.

I'm on holiday this week too with plenty of time to polish it up further, and keen to hear back about this before I'm back to my usual calendar. FWIW I am also github.com/markatcanonical Mon-Fri and could post on this thread with that login if it would help anyone get confident to try the binary :)

Thoughts?

[markshuttle]

Hmmm GH won't let me attach a tgz despite recommending that format, perhaps 28MB is too much for an attachment here? I can find another way to publish the bits if needed, perhaps just directly in the snap store, but I'd only like to do that if there is support for getting CI/CD builds and releases published automatically for all the architectures.

[grinapo]

If I understand correctly you try to generate the intial config?

I would believe that the major obstacle is not that, but to

• configure the valid certificate, matching the server name,
• configure the reverse proxy properly (usually including the aforementioned certificate), and
• for many people to configure the VOIP/group video calls seem to be both important and challenging

of which some you already mentioned (just please reformat your comment). I see that Canonical really loves snap so it's probably beneficial for Ubuntu users to have one. I believe it could even peacefully coexists with the upstream Tuwunel. :-)

I am not a developer just a loud-mouthed standbyer, but the project usually try to avoid AI generated code, so they may have prejudice. The code otherwise looks simple enough (I would even say that it would work just the same using perl or python, but of course it wouldn't be that sexy).

[markshuttle]

Yes, I agree that to make the whole thing very simple I also need to simplify the reverse-proxy and certificate steps. I am chatting with other upstreams about that. Here I just wanted to see if there was interest in the Tuwunel community to simplify the Matrix setup.

In an ideal world I could get the whole experience of getting something like Lego for Let's Encrypt certs, Caddy for reverse proxy, and Tuwunel for Matrix, down to just fix or six commands, and the whole thing should then automatically update for security fixes so that someone can just get on with life. This piece is just the Tuwunel part of that.

[grinapo]

Though I am not in the target group I am sure many people would love any way to make installation simpler. I think it's still way simpler than Synapse, and there are already a lot of good guides how to configure various revproxies, but I see that people using docker (which I despise FTR) to make their installation simpler so I'm sure many would use snap as well.

If you're thinking in an ecosystem then yes, Tuwunel part would be probably useful. But I'm the speaker for my own opinion, neither devels nor other users, and chimed in not to leave you without a resonse like nobody cared. 😏