flux/README.md

Flux

Flux is a lightweight self-hosted pseudo-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, chnage the app name, and run flux deploy and you're done!
• 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.

Limitations:

• Theoretically only supports up to 1023 containers (roughly 500 apps assuming 2 containers per app), this is because flux uses the same bridge network for all containers (this could theoretically be increased if flux was smart enough to create new networks once we hit the max, but this is not a priority)
• 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
• 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
Environment=HOME=/var/fluxd/home

[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"
}

• builder: The buildpack builder to use (default: paketobuildpacks/builder-jammy-tiny)

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,
  "env_file": ".env",
  "environment": ["DEBUG=true"]
}

Configuration Options

• name: The name of the project
• url: Domain for the application
• port: Web server's listening port
• env_file: Path to environment variable file
• environment: Additional environment variables

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