Fluitans

Server application for provisioning and managing ZeroTier networks, domain names, organizations, and registries

Named after Sargassum fluitans (the broadleaf gulfweed), one of the dominant sargassum species found in the Sargasso Sea, this server application is a prototype for a user-friendly way of managing ZeroTier networks.

Usage

The binaries generated by this project are entirely self-contained, except for the other services which Fluitans needs to talk to. You can simply run the Fluitans binary from anywhere, though you'll need to set some environment variables to specify how Fluitans should talk to the services it depends on.

Development

To install various backend development tools, run make install.

Before you start the server for the first time, you'll need to generate the webapp build artifacts by running make buildweb (which requires you to have first installed Node.js v16 (lts/gallium) and Yarn Classic). Then you can start the server using golang's go run by setting some environment variables and running make run. You will need to have installed golang first. Any time you modify the webapp files (in the web/app directory), you'll need to run make buildweb again to rebuild the bundled CSS and JS. Whenever you use a CSS selector in a template file (in the web/templates directory), you should also run make buildweb, because the build process for the bundled CSS omits any selectors not used by the templates.

Building

To execute the full build pipeline, run make; to build the docker images, run make build. You will need to have installed golang and golangci-lint first; make build should automatically install golangci-lint, but this might not work; if not, you'll need to install it manually. Note that make build will also automatically regenerate the webapp build artifacts. The resulting built binaries can be found in directories within the dist directory corresponding to OS and CPU architecture (e.g. ./dist/fluitans_window_amd64/fluitans.exe or ./dist/fluitans_linux_amd64/fluitans)

Environment Variables

You'll need to set some environment variables to tell Fluitans how to assign names and how to connect to a ZeroTier network controller. Specifically, you'll need to set:

• ZT_CONTROLLER_SERVER, which should be the URL for the ZeroTier network controller's HTTP API. It needs to include the scheme http:// or https://, for example http://localhost:9993 or https://zerotier-test.cloud.fluitans.sargassumworld.
• ZT_CONTROLLER_AUTHTOKEN, which should be the contents of the authtoken.secret file saved by ZeroTier One in its working directory (more details in ZeroTier's documentation).
• DNS_DOMAIN_NAME, which should be the parent domain name under which network domain names will be assigned, for example fluitans.org or prakashlab.dedyn.io. For web security reasons, the Fluitans app itself should be hosted on a separate domain name (for example fluitans.sargassum.world).
• DNS_SERVER, which should be the URL for the deSEC HTTP API. It needs to include the scheme https://, for example https://desec.io.
• DNS_AUTHTOKEN, which should be an authentication token for the deSEC HTTP API.
• SESSIONS_COOKIE_NOHTTPSONLY, which should be true if you are running Fluitans locally (as localhost) without HTTPS. If you are running Fluitans over the web, you should run it behind an HTTPS reverse proxy and you should leave SESSION_COOKIE_NOHTTPSONLY unset.
• SESSIONS_AUTH_KEY, which should be set to a session key generated by running Fluitans without the SESSION_AUTH_KEY set.
• SESSIONS_ENCRYPTION_KEY, which should be set to a session encryption key generated by running pslive without the SESSION_ENCRYPTION_KEY set.
• AUTHN_ADMIN_PW_HASH, which should be set to the password hash generated by running Fluitans with a password set as AUTHN_ADMIN_PW.
• ACTIONCABLE_HASH_KEY, which should be set to an HMAC key generated by running Fluitans without the ACTIONCABLE_HASH_KEY set.

For example, you could generate the password and session key and Turbo Streams hash key using:

AUTHN_ADMIN_PW='mypassword' make run

which will print a message like:

Record this admin password hash for future use as AUTHN_ADMIN_PW_HASH
(use single-quotes from shell to avoid string substitution with dollar-signs):
$argon2id$v=19$m=65536,t=1,p=2$EIV/HJ0DILHeNf2IC+qsGQ$BvBCCEsKUCKuAPI+pzM+sbCy/pdQdOF/FmHwx/yIusU
Record this key for future use as SESSIONS_AUTH_KEY: QVG4y5EPPoDZjAzYc6j7I09iJum3w+hXNrB3O4HQvSc=
Record this key for future use as SESSIONS_ENCRYPTION_KEY: Z/47Z2Uf6J68VFf7uAjiTfmum3yKWRuR2KoLVhwVdYA=
Record this key for future use as ACTIONCABLE_HASH_KEY: S+daMZsQxsqjmINunGWJhXvvxcgJtqnACba+sFuC4Tc=

And then you could run the server in development mode (which you can log into with username admin and password mypassword) using:

ZTCONTROLLER_SERVER='http://localhost:9993' \
ZTCONTROLLER_AUTHTOKEN='0123456789abcdefghijklmn' \
DNS_DOMAIN_NAME='fluitans.org' \
DNS_SERVER='https://desec.io' \
DNS_AUTHTOKEN='abcdefghijklmn0123456789' \
SESSION_AUTH_KEY='QVG4y5EPPoDZjAzYc6j7I09iJum3w+hXNrB3O4HQvSc=' \
SESSIONS_ENCRYPTION_KEY='Z/47Z2Uf6J68VFf7uAjiTfmum3yKWRuR2KoLVhwVdYA=' \
AUTHN_ADMIN_PW_HASH='$argon2id$v=19$m=65536,t=1,p=2$EIV/HJ0DILHeNf2IC+qsGQ$BvBCCEsKUCKuAPI+pzM+sbCy/pdQdOF/FmHwx/yIusU' \
ACTIONCABLE_HASH_KEY='S+daMZsQxsqjmINunGWJhXvvxcgJtqnACba+sFuC4Tc=' \
make run

Or you could run the built binary using:

ZTCONTROLLER_SERVER='http://localhost:9993' \
ZTCONTROLLER_AUTHTOKEN='0123456789abcdefghijklmn' \
DNS_DOMAIN_NAME='fluitans.org' \
DNS_SERVER='https://desec.io' \
DNS_AUTHTOKEN='abcdefghijklmn0123456789' \
SESSION_AUTH_KEY='QVG4y5EPPoDZjAzYc6j7I09iJum3w+hXNrB3O4HQvSc=' \
AUTHN_ADMIN_PW_HASH='$argon2id$v=19$m=65536,t=1,p=2$EIV/HJ0DILHeNf2IC+qsGQ$BvBCCEsKUCKuAPI+pzM+sbCy/pdQdOF/FmHwx/yIusU' \
ACTIONCABLE_HASH_KEY='S+daMZsQxsqjmINunGWJhXvvxcgJtqnACba+sFuC4Tc=' \
./fluitans

License

Copyright Prakash Lab and the Sargassum project contributors.

SPDX-License-Identifier: Apache-2.0 OR BlueOak-1.0.0

You can use this project either under the Apache 2.0 License or under the Blue Oak Model License 1.0.0; you get to decide. We chose the Apache license because it's OSI-approved, and because it goes well together with the Solderpad Hardware License, which is a license for open hardware used in other related projects but not this project. We prefer the Blue Oak Model License because it's easier to read and understand.