https://github.com/n0rdy/forq
Simple (but highly opinionated) MQ server powered by SQLite. Single binary. No extra dependencies needed.
https://github.com/n0rdy/forq
daisyui foss go golang htmx htmx-go message-queue mq self-hosted sqlite sqlite3
Last synced: 5 days ago
JSON representation
Simple (but highly opinionated) MQ server powered by SQLite. Single binary. No extra dependencies needed.
- Host: GitHub
- URL: https://github.com/n0rdy/forq
- Owner: n0rdy
- License: agpl-3.0
- Created: 2025-08-28T20:43:09.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T16:03:00.000Z (12 days ago)
- Last Synced: 2026-04-19T18:08:26.786Z (12 days ago)
- Topics: daisyui, foss, go, golang, htmx, htmx-go, message-queue, mq, self-hosted, sqlite, sqlite3
- Language: Go
- Homepage: https://forq.sh
- Size: 13.8 MB
- Stars: 9
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Forq - Simple Message Queue powered by SQLite
Forq is a simple single-binary message queue on top of SQLite, designed for small to medium workloads. Shipped with the Admin UI for easy management.
The assumption is that you will self-host Forq on a VPS or a small cloud instance, and use it for background jobs, task queues, or inter-service communication.
While Forq has a limited set of features compared to more complex systems like RabbitMQ or Kafka, it is extremely easy to set up and use, has a very low resource footprint, and easy to maintain.
No external dependencies are required, as SQLite is embedded.
## Open-source but closed-contribution
Forq is open-source, but I do not accept external contributions.
This is a personal project, and I want to keep full control over the codebase and direction of the project.
Also, I don't feel I have enough free time to review and manage contributions (if any).
Therefore, please do not open PRs.
If you find any bugs, have questions or suggestions, use the `Discussions` section for that.
## Quick Start
### Prerequisites
- Go 1.26+ (for building from source)
- Or use Docker
### Installation
#### Build from Source
```bash
git clone https://github.com/n0rdy/forq.git
cd forq
go build -o forq ./main.go
```
#### Docker
```bash
docker run -d \
--name forq \
--restart unless-stopped \
-e FORQ_AUTH_SECRET=your-auth-secret-min-32-chars-long \
-e FORQ_DB_PATH=/app/data/forq/forq.db \
-e FORQ_API_ADDR=0.0.0.0:8080 \
-e FORQ_UI_ADDR=0.0.0.0:8081 \
-p 8080:8080 \
-p 8081:8081 \
-v ~/forq-data:/app/data/forq \
mykonordy/forq:latest
```
**For Docker, these env vars must be set:**
- `FORQ_DB_PATH` - Sets explicit database location inside container
- `FORQ_API_ADDR=0.0.0.0:8080` - Binds API to all interfaces (required for Docker port mapping)
- `FORQ_UI_ADDR=0.0.0.0:8081` - Binds UI to all interfaces (required for Docker port mapping)
Please, note that if you are running Forq via Docker on macOS, the performance will be significantly worse due to Docker's filesystem performance issues on macOS.
I'd advise against running Forq on macOS via Docker in production. Binary always gives the best performance.
### Configuration
Forq uses environment variables for configuration:
```bash
# Required
export FORQ_AUTH_SECRET=your-auth-secret-min-32-chars-long # to use for API and Admin UI authentication
export FORQ_DB_PATH=./data/forq.db # path to the SQLite database file
# Optional
export FORQ_METRICS_ENABLED=false # true|false (default: false)
export FORQ_METRICS_AUTH_SECRET=your-metrics-secret-min-32-chars-long # required if FORQ_METRICS_ENABLED is true
export FORQ_ENV=pro # local|pro (default: pro)
export FORQ_QUEUE_TTL_HOURS=24 # Default: 24 hours
export FORQ_DLQ_TTL_HOURS=168 # Default: 168 hours (7 days)
export FORQ_API_ADDR=localhost:8080 # Default: localhost:8080
export FORQ_UI_ADDR=localhost:8081 # Default: localhost:8081
```
### Running Forq
```bash
./forq
# Server starts on :8080 (API) and :8081 (UI) by default
```
### First Message
Send your first message:
```bash
curl -X POST http://localhost:8080/api/v1/queues/emails/messages \
-H "X-API-Key: your-auth-secret-min-32-chars-long" \
-H "Content-Type: application/json" \
-d '{"content": "I am going on an adventure!"}'
```
where `emails` is the queue name. If the queue does not exist, it will be created automatically.
Receive the message:
```bash
curl -X GET http://localhost:8080/api/v1/queues/emails/messages \
-H "X-API-Key: your-auth-secret-min-32-chars-long"
```
Acknowledge the message:
```bash
curl -X POST http://localhost:8080/api/v1/queues/emails/messages/{message_id}/ack \
-H "X-API-Key: your-auth-secret-min-32-chars-long"
```
where `{message_id}` is the `id` of the message received in the previous step.
## SDKs
I implemented simple Forq SDKs for the ecosystems that I use most often:
- [Go](https://github.com/n0rdy/forq-sdk-go)
- [Java](https://github.com/n0rdy/forq-sdk-java)
- [TypeScript](https://github.com/n0rdy/forq-sdk-typescript)
Those are very simple, and basically just wrap the HTTP API.
If your platform of choice is not listed here, you can generate the client code using the [Forq OpenAPI specification](https://github.com/n0rdy/forq/blob/main/openapi.yaml),
or just use the HTTP API directly. The whole API consists of 4 endpoint and 3 models, no big deal.
## Next Steps
- [Philosophy](https://forq.sh/documentation-portal/docs/guides/philosophy/) - A very short read about philosophy behind Forq. Helps to understand the design decisions.
- [Specification](https://forq.sh/documentation-portal/docs/guides/specification/) - Overview of Forq features and design, do check it out!
- [Configurations](https://forq.sh/documentation-portal/docs/guides/configurations/) - All configuration options
- [Producing Messages](https://forq.sh/documentation-portal/docs/guides/producing-messages/) - How to send messages to queues
- [Consuming Messages](https://forq.sh/documentation-portal/docs/guides/consuming-messages/) - How to receive and acknowledge messages
- [Metrics](https://forq.sh/documentation-portal/docs/guides/metrics/) - Setting up monitoring with Prometheus
- [Admin UI Guide](https://forq.sh/documentation-portal/docs/guides/admin-ui/) - Using the admin interface
- [API Reference](https://forq.sh/documentation-portal/docs/reference/api/) - Complete API documentation
- [SDKs](https://forq.sh/documentation-portal/docs/reference/sdks/) - Client libraries for various languages
- [Forq vs Other MQs](https://forq.sh/documentation-portal/docs/guides/forq-vs-other-mqs/) - Comparison with other message queue systems
- [Forq Internals](https://forq.sh/documentation-portal/docs/guides/internals/) - How (and why) Forq works under the hood for fellow nerds