{"id":50863638,"url":"https://github.com/dannote/just-bun","last_synced_at":"2026-06-14T23:05:39.304Z","repository":{"id":324777224,"uuid":"1098504034","full_name":"dannote/just-bun","owner":"dannote","description":"Opinionated Bun + Elysia + Vue Starter","archived":false,"fork":false,"pushed_at":"2026-02-08T16:53:57.000Z","size":320,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-27T16:38:59.595Z","etag":null,"topics":["bun","elysia","single-binary","sqlite","starter-kit","systemd","vue"],"latest_commit_sha":null,"homepage":"","language":"Just","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dannote.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-17T19:22:41.000Z","updated_at":"2026-04-14T09:26:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dannote/just-bun","commit_stats":null,"previous_names":["dannote/just-bun"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dannote/just-bun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannote%2Fjust-bun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannote%2Fjust-bun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannote%2Fjust-bun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannote%2Fjust-bun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dannote","download_url":"https://codeload.github.com/dannote/just-bun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannote%2Fjust-bun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34340834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","elysia","single-binary","sqlite","starter-kit","systemd","vue"],"created_at":"2026-06-14T23:05:38.492Z","updated_at":"2026-06-14T23:05:39.299Z","avatar_url":"https://github.com/dannote.png","language":"Just","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Just Bun! — Opinionated Bun + Elysia + Vue Starter\n\nSkip Docker pulls. Ship a single Bun binary with a Vue frontend, using Bun's\nbundler, test runner, and SQLite.\n\n\u003cp\u003e\n  \u003cimg src=\"app/assets/logos/bun.svg\" alt=\"Bun logo\" width=\"64\" /\u003e\n  \u003cimg src=\"app/assets/logos/vite.svg\" alt=\"Vite logo\" width=\"64\" /\u003e\n  \u003cimg src=\"app/assets/logos/vue.svg\" alt=\"Vue logo\" width=\"64\" /\u003e\n  \u003cimg src=\"app/assets/logos/elysia.svg\" alt=\"Elysia logo\" width=\"64\" /\u003e\n  \u003cimg src=\"app/assets/logos/arktype.svg\" alt=\"ArkType logo\" width=\"64\" /\u003e\n  \u003cimg src=\"app/assets/logos/shadcn-vue.svg\" alt=\"shadcn-vue logo\" width=\"64\" /\u003e\n  \u003cimg src=\"app/assets/logos/reka-ui.svg\" alt=\"Reka UI logo\" width=\"64\" /\u003e\n  \u003cimg src=\"app/assets/logos/cva.svg\" alt=\"CVA logo\" width=\"64\" /\u003e\n\u003c/p\u003e\n\n## Motivation\nI was tired of slow Docker builds and container registries for every small change. This starter leans on [Bun](https://bun.sh) and [Vite](https://vite.dev) to ship a single binary with a Vue 3 frontend.\n\n## Why this starter\n- Bun-native toolchain: built-in bundler, `bun:test`, `bun:sqlite`, `Bun.serve`, and an S3-friendly runtime so you ship more with fewer deps—no extra SDKs required.\n- Fast API layer: [Elysia](https://elysiajs.com) + [ArkType](https://arktype.io) give typed routes that stay close to the edge.\n- Modern UI: [Vue 3](https://vuejs.org) SFCs with auto-routed pages, [shadcn-vue](https://www.shadcn-vue.com) + [Reka UI](https://reka-ui.com) primitives, and [CVA](https://beta.cva.style)-driven variants.\n- Minimal DevOps: build a single executable, [rsync](https://rsync.samba.org), and let [systemd](https://systemd.io) + [Caddy](https://caddyserver.com) keep it running—no images or registries required.\n\n## Getting started\nThe shortest path is: install `just`, run `just bun`, and start the dev server. You can scaffold with Bun or clone the repo.\n\n**Using `bun create`**\n\n```bash\nbun create dannote/just-bun my-app\n```\n\n**Cloning directly**\n\n```bash\njust install\ncp .env.example .env.local\njust dev\n```\n\nWhen you're ready to ship, create a production env file:\n\n```bash\ncp .env.example .env.production\n```\n\n## Environment\n- `.env.local` is for local development.\n- `.env.production` is read at deploy time.\n- `.env.example` documents the full set; copy from it instead of committing secrets.\n\nKey variables:\n- `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_GROUP`: SSH target for rsync/systemd.\n- `DEPLOY_PROJECT_NAME`, `DEPLOY_TARGET`: control where the compiled binary lands and which Bun target to build.\n\n## Just setup\nInstall [`just`](https://just.systems) first—installing `just` lets you run `just bun`, which installs Bun for you, so you literally install just to install bun and end up with Just Bun!. One straight-line way to see it:\n\n```\n# Install Just\ncurl https://just.systems/install.sh | bash -s -- --to /usr/local/bin\n\n# Install Bun\njust bun\n\n# Deploy\njust deploy\n```\n\nPrefer packages? Grab `just` via:\n\n- macOS: `brew install just`\n- Ubuntu: `sudo apt-get install just`\n- Fedora: `sudo dnf install just`\n- Other distros: see the package list at [just.systems/man/en/packages](https://just.systems/man/en/packages.html).\n\nAfter installing `just`, run `just bun` to fetch Bun if it is not on your PATH. Verify `just --version`, then explore available tasks with `just --list`. Read the full docs at [just.systems/man](https://just.systems/man/en/) if you want to extend the taskfile.\n\n## Commands\n- `just bun` — install Bun if it is not already available.\n- `just dev` — run the full stack locally.\n- `just build` — [Vite](https://vite.dev) build + [Nitro](https://nitro.unjs.io) output.\n- `just test` — bun:test example suite.\n- `just format` / `just lint` — [Biome](https://biomejs.dev) + [oxlint](https://oxc-project.github.io/oxlint/) for consistency.\n- `just app release` — compile the server to a static Bun binary in `releases/`.\n- `just ssh` — open an interactive shell on the deploy target.\n- `just repo collect|status|verify` — manage the local binary repository. See [The repository](#the-repository).\n- `just app start|stop|restart|status` — manage the app service.\n- `just app enable|disable` — enable or disable the app service without removing files.\n- `just app logs \u003cjournalctl args\u003e` — stream service logs like `just app logs -f`.\n- `just app console` — open an interactive console on the server (requires `ENABLE_CONSOLE=1`).\n- `just app version` — show currently deployed version hash.\n- `just app versions` — list all available versions on server.\n- `just app rollback [hash]` — rollback to previous version or a specific hash.\n- `just app prune` — remove old binary versions, keeping latest 3.\n- `just app uninstall` — remove service, configs, binaries, and all app data.\n- `just db migrate|status|new|rollback` — manage database migrations with [Kysely](https://kysely.dev).\n- `just host apps` — list all apps deployed on the server.\n- `just host databases` — list all SQLite databases on the server.\n- `just host services` — list running app services on the server.\n- `just deploy` — build, upload, and restart everything in one command.\n\n## End-to-end tests\n\nThe deployment workflow has a lot of moving parts: building binaries, uploading via rsync, managing symlinks, configuring systemd, and coordinating restarts. To verify everything works together, the `recipes/e2e/` directory contains a full end-to-end test suite.\n\nThe tests spin up a Fedora container with systemd using Docker that mimics a real production server. They then run through the entire deployment lifecycle—build, release, upload, service setup, start/stop, rollback, and cleanup—verifying each step works correctly. This catches integration issues that unit tests miss, like permission problems, missing dependencies, or broken systemd configurations.\n\nTests are written in [Bats](https://github.com/bats-core/bats-core), the Bash Automated Testing System, which keeps them readable and close to the actual shell commands you'd run manually. Run `just e2e test` to execute the full suite, or use `just e2e ssh` to drop into the test container for debugging.\n\n- `just e2e test` — run all e2e tests against a local container.\n- `just e2e test deploy` — run only deployment tests.\n- `just e2e test forgejo` — run only Forgejo tests.\n- `just e2e test litestream` — run only Litestream replication tests (starts MinIO S3).\n- `just e2e clean` — tear down the test container.\n- `just e2e ssh` — SSH into the test container for debugging.\n\n## Deployment\nThis starter compiles the backend into a single executable with [`bun build --compile`](https://bun.sh/docs/bundler/executables). Deployment uses [rsync](https://rsync.samba.org) with delta transfers—only changed bytes are uploaded, making iterative deploys fast even for large binaries. A symlink flip enables instant rollback to any previous version. [systemd](https://systemd.io) keeps the process healthy, and [Caddy](https://caddyserver.com) fronts it with automatic TLS.\n\nCaddy fetches and renews Let's Encrypt certificates automatically for any configured domain as soon as DNS points at your server. Service templates live in `configs/`, keeping secrets out of version control.\n\nThe deployment follows standard [FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) paths:\n\n```\n/usr/local/bin/\n├── just-bun -\u003e just-bun.a1b2c3d      # symlink to current version\n├── just-bun.a1b2c3d                  # current binary\n├── just-bun.f4e5d6c                  # previous version (instant rollback)\n├── caddy\n├── forgejo\n└── vector\n\n/etc/\n├── just-bun/\n│   └── .env.production\n├── caddy/\n│   ├── Caddyfile\n│   └── sites.d/\n│       ├── just-bun.caddy\n│       └── forgejo.caddy\n├── forgejo/\n│   └── app.ini\n└── vector/\n    └── vector.yaml\n\n/var/www/just-bun/                    # static assets served by Caddy\n├── index.html\n├── favicon.svg\n└── assets/\n\n/var/lib/just-bun/                    # app working directory\n└── app.db                            # SQLite database\n\n/var/lib/forgejo/                     # Forgejo working directory\n├── data/\n│   ├── forgejo.db                    # Forgejo SQLite database\n│   └── repositories/                 # Git repositories\n└── custom/                           # custom templates and assets\n\n/var/cache/just-bun/                  # rsync target for delta transfers\n└── just-bun\n```\n\n## Accessories\nAccessory services live under `recipes/accessories/` and follow the same\ndeploy-and-manage flow as the app: rsync a pinned binary, render configs from\n`configs/`, and let systemd supervise it. They are intentionally optional, so\nyou can turn them on only when you need them. Caddy fronts the app with TLS and\nstatic assets, Vector ships journald logs to S3, Litestream replicates SQLite\ndatabases to S3, and Forgejo adds a self-hosted Git forge. Each one can be\ndeployed and managed independently via `just caddy`, `just litestream`,\n`just vector`, or `just forgejo`.\n\n- `just caddy deploy|start|stop|restart|status` — manage the Caddy reverse proxy.\n- `just forgejo deploy|start|stop|restart|status` — manage the Forgejo Git forge.\n- `just forgejo generate-secrets` — generate secrets for Forgejo's app.ini.\n- `just forgejo add-remote [name]` — add Forgejo as Git remote for current repo.\n- `just litestream deploy|start|stop|restart|status` — manage the Litestream replication.\n- `just litestream restore [db]` — restore database from S3 (defaults to current app's DB).\n- `just litestream snapshots [db]` — list snapshots (defaults to current app's DB).\n- `just litestream databases` — show which databases are being replicated.\n- `just vector deploy|start|stop|restart|status` — manage the Vector log aggregator.\n\n## The repository\n\nDocker solved dependency distribution by bundling everything into container images. But images are opaque blobs that hide what's actually running, require a registry to host, and add cold-start latency. This starter takes a different approach: static binaries distributed directly.\n\nThe `repo/` directory is a local binary repository organized by platform. Instead of pulling container images, you collect verified binaries once and rsync them to your servers:\n\n```bash\njust repo collect        # download and verify all binaries\njust repo status         # see what's in your local repo\njust repo verify         # re-verify checksums\n```\n\nEach binary is version-pinned and checksum-verified against upstream signatures. The repo structure mirrors target platforms, so you can cross-deploy from any development machine:\n\n```\nrepo/\n├── linux/\n│   └── amd64/\n│       ├── caddy.2.10.2\n│       ├── caddy.2.10.2.sig\n│       ├── forgejo.13.0.3\n│       ├── forgejo.13.0.3.sig\n│       ├── litestream.0.5.5\n│       ├── litestream.0.5.5.sig\n│       ├── vector.0.52.0\n│       ├── vector.0.52.0.sig\n│       └── just-bun.a1b2c3d\n└── darwin/\n    └── arm64/\n        └── ...\n```\n\nThis approach means you always know exactly what's running because it's right there in `repo/`, deployments are reproducible without network access to registries, and there's no container runtime overhead. Your app, Caddy, Vector, and any other tools are just executables managed by systemd.\n\n## Stack highlights\n- **[Bun](https://bun.sh) runtime**: fast start, built-in bundler, `bun:test`, `bun:sqlite`, native HTTP, and an S3-capable runtime without extra SDKs.\n- **[Kysely](https://kysely.dev)**: type-safe SQL query builder with migrations, wired to `bun:sqlite`.\n- **[Elysia](https://elysiajs.com) + [ArkType](https://arktype.io)**: ergonomic, typed HTTP handlers for the API surface.\n- **[Vue 3](https://vuejs.org) SFC + [Vite](https://vite.dev)**: auto-routed pages, hot reload, and TypeScript-first ergonomics.\n- **[shadcn-vue](https://www.shadcn-vue.com) + [Reka UI](https://reka-ui.com) + [CVA](https://beta.cva.style)**: accessible primitives with typed variants to keep props sane.\n- **[Unhead](https://unhead.unjs.io)**: declarative head/meta management for Vue out of the box.\n- **[Logtape](https://logtape.dev)**: structured logging wired for console in dev and syslog in production.\n- **[OpenTelemetry](https://opentelemetry.io)**: distributed tracing with OTLP export to any compatible backend.\n- **[Vector](https://vector.dev)**: log aggregation from journald with S3 export for observability.\n- **[Litestream](https://litestream.io)**: streaming SQLite replication to S3—continuous backups without stopping writes.\n- **[Forgejo](https://forgejo.org)**: self-hosted Git forge you can deploy as a single binary alongside your app.\n\n## What you get out of the box\n- A home page that showcases the stack and links you to the docs and API example.\n- A typed `/api/hello` route you can extend.\n- An example bun:test in `test/api.test.ts` to keep the lights green.\n- Opinionated defaults for formatting, linting, and routing that stay out of your way.\n\n## Philosophy\nKeep the stack small, keep the feedback loop tight, and ship binaries instead of containers when you can. Lean on Bun's built-ins before adding dependencies, and prefer well-typed primitives (Elysia, ArkType, CVA, shadcn-vue) over bespoke glue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannote%2Fjust-bun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannote%2Fjust-bun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannote%2Fjust-bun/lists"}