192 lines
5.0 KiB
Markdown
192 lines
5.0 KiB
Markdown
# Flux
|
|
|
|
Flux is a lightweight self-hosted pseudo-PaaS for hosting Golang web apps with ease. Built on top of [Buildpacks](https://buildpacks.io/) and [Docker](https://docs.docker.com/get-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 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](https://golang.org/dl/)
|
|
- [ZQDGR](https://github.com/juls0730/zqdgr)
|
|
- [Buildpacks](https://buildpacks.io/) (daemon only)
|
|
- [Docker](https://docs.docker.com/get-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](https://github.com/mattn/go-sqlite3)
|
|
|
|
#### Method 1: ZQDGR
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|