flux/README.md

Flux

Flux is a lightweight self-hosted micro-PaaS for hosting Golang web apps with ease. Built on top of Buildpacks and Docker, Flux simplifies the deployment process with a focus on similicity, speed, and reliability.

Goals:

• Automatic deployment of Golang web apps, simply run flux init, and run flux deploy to deploy your app!
• Zero-downtime deployments with blue-green deployments
• Simple but powerful configuration, flux should be able to handle most use cases, from a micro web app to a fullstack app with databases, caching layers, full text search, etc.

What is flux not?

• Flux is not meant to be used as a multi-tenant PaaS, it is meant to be used by trusted individuals, while flux will still have security in mind, certain things are not secure. For example, anyone can delete all your apps, so be careful, anyone who has access to your flux server can do a lot of damage.

Limitations:

• Theoretically flux is likely limited by the amount of containers can fit in the bridge network, but I haven't tested this
• Containers are not particularly isolated, if one malicious container wanted to scan all containers, or interact with other containers it tectically shouldnt, it totally just can (todo?)

Features

• Blue-Green Deployments: Deploy new versions of your app without downtime
• Simplify Deployment: Flux takes care of the deployment process, so you can focus on writing your app
• Flexible Configuration: Easily configure your app with flux.json
• Automatic Container Management: Steamline your app with automatic container management

Dependencies

• Go
• ZQDGR (development only)
• Buildpacks (daemon only)
• Docker (daemon only)

Intallation

Daemon

To install and start the Flux daemon using ZQDGR, run the following command:

Important

CGO is required to build the daemon due to the use of mattn/go-sqlite3

Method 1: ZQDGR

go install github.com/juls0730/zqdgr@latest

git clone https://github.com/juls0730/flux.git
cd flux

# either
zqdgr build:daemon
sudo ./fluxd

# or
FLUXD_ROOT_DIR=$PWD/fluxdd zqdgr run:daemon

Method 2: Docker

docker run -d --name fluxd --network host -v /var/run/docker.sock:/var/run/docker.sock -v fluxd-data:/var/fluxd -p 5647:5647 -p 7465:7465 zoeissleeping/fluxd:latest

Method 3: Systemd

go install github.com/juls0730/zqdgr@latest

git clone https://github.com/juls0730/flux.git
cd flux

zqdgr build:daemon
sudo mv fluxd /usr/local/bin/

cat <<EOF
[Unit]
Description=Flux Daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/fluxd
Restart=always
Environment=GOPATH=/var/fluxd/go

[Install]
WantedBy=multi-user.target
EOF | sudo tee /etc/systemd/system/fluxd.service

sudo systemctl daemon-reload
sudo systemctl enable --now fluxd

CLI

Install the CLI using the following command:

go install github.com/juls0730/flux/cmd/flux@latest

Configuration

Daemon

Flux daemon looks for a confgiuration file in /var/fluxd/config.json but can be configured by setting $FLUXD_ROOT_DIR to the directory where you want all fluxd files to be stored.

{
  "builder": "paketobuildpacks/builder-jammy-tiny",
  "disable_delete_all": false,
  "compression": {
    "enabled": false
  }
}

• builder: The buildpack builder to use (default: paketobuildpacks/builder-jammy-tiny)
• disable_delete_all: Disable the delete all deployments endpoint (default: false)
• compression: Compression settings
  • enabled: Enable compression (default: false)
  • level: Compression level

Daemon Settings

• Default port: 5647 (Daemon server)
• Reverse Proxy Port: 7465 (configurable via FLUXD_PROXY_PORT environment variable)

CLI

The CLI looks for a configuration file in ~/.config/flux/config.json:

{
  "daemon_url": "http://127.0.0.1:5647"
}

• daemon_url: The URL of the daemon to connect to (default: http://127.0.0.1:5647)

Commands

Flux <command>

Available commands:

• init: Initialize a new project
• deploy: Deploy an application
• start: Start an application
• stop: Stop an application
• delete: Delete an application
• list: View application logs

Project Configuration (flux.json)

flux.json is the configuration file in the root of your proejct that defines deployment settings:

{
  "name": "my-app",
  "url": "myapp.example.com",
  "port": 8080,
  "containers": [
    {
        "name": "redis",
        "image": "redis:latest",
        "volumes": [
            {
                "mountpoint": "/data"
            }
        ],
    }
  ],
  "env_file": ".env",
  "environment": ["DEBUG=true"]
}

The project config files has the following options:

field	description	required
name	The name of the project	true
url	Domain for the application	true
port	Web server's listening port	true
env_file	Path to environment variable file	false
environment	Additional environment variables	false
containers	Supplemental containers to run alongside the app	false
volumes	Volumes to mount to the app's containers	false

Deployment Notes

• After deploying an app, point your domain to the Flux reverse proxy
• Ensure the Host header is sent with your requests

Contributing

Found a bug, or have something you think would make Flux better? Submit an issue or pull request.

License

Flux is licensed with the MIT license