fluitans

module

v0.8.0 Latest Latest Go to latest Published: Feb 23, 2023 License: Apache-2.0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/sargassum-world/fluitans

Links

Open Source Insights

README ¶

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.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
fluitans
db Package db contains application-specific db schemas and scripts	Package db contains application-specific db schemas and scripts
internal
app/fluitans Package fluitans provides the Fluitans server.	Package fluitans provides the Fluitans server.
app/fluitans/auth Package auth provides application-level standardization for authentication	Package auth provides application-level standardization for authentication
app/fluitans/client Package client contains client code for external APIs	Package client contains client code for external APIs
app/fluitans/conf Package conf supports environment variable-based application configuration	Package conf supports environment variable-based application configuration
app/fluitans/handling Package handling provides utilities for handlers	Package handling provides utilities for handlers
app/fluitans/routes Package routes contains the route handlers for the Fluitans server.	Package routes contains the route handlers for the Fluitans server.
app/fluitans/routes/assets Package assets contains the route handlers for assets which are static for the server	Package assets contains the route handlers for assets which are static for the server
app/fluitans/routes/auth Package auth contains the route handlers related to authentication and authorization.	Package auth contains the route handlers related to authentication and authorization.
app/fluitans/routes/cable Package cable contains the route handlers serving Action Cables over WebSockets by implementing the Action Cable Protocol (https://docs.anycable.io/misc/action_cable_protocol) on the server.	Package cable contains the route handlers serving Action Cables over WebSockets by implementing the Action Cable Protocol (https://docs.anycable.io/misc/action_cable_protocol) on the server.
app/fluitans/routes/controllers Package controllers contains the route handlers related to ZeroTier controllers.	Package controllers contains the route handlers related to ZeroTier controllers.
app/fluitans/routes/dns Package dns contains the route handlers related to DNS records	Package dns contains the route handlers related to DNS records
app/fluitans/routes/home Package home contains the route handlers related to the app's home screen.	Package home contains the route handlers related to the app's home screen.
app/fluitans/routes/networks Package networks contains the route handlers related to ZeroTier networks.	Package networks contains the route handlers related to ZeroTier networks.
app/fluitans/tmplfunc Package tmplfunc contains extension functions for templates	Package tmplfunc contains extension functions for templates
app/fluitans/workers Package workers provides functionality which runs independently of request servicing.	Package workers provides functionality which runs independently of request servicing.
clients/desec Package desec provides a high-level client to the deSEC API	Package desec provides a high-level client to the deSEC API
clients/zerotier Package zerotier provides a high-level client for the Zerotier network controller API	Package zerotier provides a high-level client for the Zerotier network controller API
clients/ztcontrollers Package ztcontrollers provides a high-level client for management of Zerotier network controllers	Package ztcontrollers provides a high-level client for management of Zerotier network controllers
models Package models provides shared data models	Package models provides shared data models
pkg
desec Package desec provides generic client code for the deSEC DNS server API	Package desec provides generic client code for the deSEC DNS server API
slidingwindows Package slidingwindows provides a multi-sliding-window meter for rate-limiting API requests	Package slidingwindows provides a multi-sliding-window meter for rate-limiting API requests
zerotier Package zerotier provides primitives to interact with the openapi HTTP API.	Package zerotier provides primitives to interact with the openapi HTTP API.
web Package web contains web application-specific components: static web assets, server-side templates, and modest JS sprinkles and spots.	Package web contains web application-specific components: static web assets, server-side templates, and modest JS sprinkles and spots.