Skip to content
newstack-cloudPublic

About

Your whole system, running locally: every service and the infrastructure behind it, wired together over HTTPS on real local domains, with one command.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

86 Commits

Folders and files

Repository files navigation

lo1

Your whole system, running locally

CI Coverage Security Rating Maintainability Rating NPM Version

Multi-service local development environment. Orchestrate services, infrastructure, and reverse proxying with a single lo1 up.

lo = loopback interface, 1 from ::1 (IPv6 loopback)

lo1-demo.mp4

Packages

Package Description
@lo1/cli CLI application — lo1 init, lo1 up, lo1 down, lo1 status
@lo1/sdk Plugin SDK — types, config schemas, and utilities for plugin authors
@lo1/plugin-celerity Celerity plugin — blueprint-driven compose, provisioning, and seeding

Prerequisites

Dependency Version Purpose
Node.js 24+ CLI runtime
Docker 20.10+ Container services, infrastructure, reverse proxy
Git 2.x Repository cloning (lo1 init)

Docker Compose v2 is included with Docker Desktop (macOS/Windows) and modern Docker Engine (Linux).

lo1 runs on macOS, Linux and Windows. On Windows, run it from PowerShell with Docker Desktop. Inside WSL 2, lo1 sets up the hosts file and certificate authority in Linux only, so browsers on Windows won't reach or trust the workspace.

On Linux with TLS enabled, also install certutil, which lo1 uses to add its certificate authority to Chrome and Firefox. Those browsers don't read the system store:

sudo apt install libnss3-tools   # Debian, Ubuntu
sudo dnf install nss-tools       # Fedora
sudo pacman -S nss               # Arch

Quick Start

lo1 runs on Node.js 24 or later. You can install it with npm, pnpm, Yarn or Bun, but Node.js is still needed: the lo1 command runs on Node whichever package manager installed it.

# Install globally (pick your package manager)
npm install -g @lo1/cli    # npm
pnpm add -g @lo1/cli       # pnpm
yarn global add @lo1/cli   # Yarn
bun install -g @lo1/cli    # Bun

# Initialize a workspace (clones repositories, sets up infrastructure)
lo1 init

# Start all services
lo1 up

# Check service status
lo1 status

# Stop everything
lo1 down

Configuration

Define your workspace in lo1.yaml:

version: "1"
name: my-project

services:
  api:
    type: service
    path: ./services/api
    port: 3000
    command: bun run dev

  frontend:
    type: app
    path: ./services/web
    port: 5173
    command: bun run dev

proxy:
  tld: local
  tls:
    enabled: true

The @lo1/sdk package publishes a JSON Schema for IDE autocompletion and validation.

TLS

proxy.tls.mode picks how the proxy gets its certificates.

internal (default)

Caddy's built-in CA issues the certificates, and lo1 up installs the root into the host trust store. Only the machine running lo1 trusts them, so other devices on the LAN will see certificate warnings.

  • macOS: your login keychain, which may show a password dialog the first time.
  • Linux: the system store (needs sudo), plus Chrome's and Firefox's stores when certutil is installed.
  • Windows: your user's certificate store, after Windows asks you to confirm the "Caddy Local Authority" certificate.

On Windows, writing the hosts file needs administrator rights, so unless PowerShell is running as Administrator, lo1 up shows a UAC prompt.

acme

Caddy obtains and renews publicly trusted certificates itself over the DNS-01 challenge, so every device on the network accepts them with nothing to install. Because the stock Caddy image cannot solve DNS challenges, lo1 rebuilds the proxy image with the matching caddy-dns provider module.

proxy:
  tld: dev # a real domain you control, e.g. my-project.dev
  tls:
    enabled: true
    mode: acme
    acme:
      provider: cloudflare # any caddy-dns provider name
      tokenEnv: CF_API_TOKEN # host env var holding the DNS API credential
      email: me@example.com # ACME account email
      domains: ["*.my-project.dev"] # names ACME should cover
      ca: letsencrypt # or "staging" while you are testing
      resolvers: ["1.1.1.1"]
      propagationTimeout: 5m

The credential is passed to the container by name (${CF_API_TOKEN}), so the secret never lands in a generated file. Export it in the shell you run lo1 up from. A .env file is not enough on its own, because lo1 checks the process environment and fails before Docker Compose would interpolate one.

domains declares which names ACME issues for. Hosts covered by a wildcard are folded into a single site block, so Caddy orders one certificate for the whole set rather than one per service, and adding a service needs no new issuance.

Anything that does not match domains falls back to the internal CA, which is what lets a workspace mix the two. A service given proxy.domain: api.local.example.com gets a publicly trusted certificate, while the default api.<workspace>.local host keeps using Caddy's local CA, since no public CA can issue for a .local name. Leaving domains empty lets ACME cover every site, which only works if every host is a public name.

Renewal is entirely Caddy's job. It renews in the background and reloads itself, so there is no external ACME client to run and no reload hook to wire up.

Other providers work the same way. Set provider to route53, digitalocean, azure, or any other name matching a module in the caddy-dns org. Providers needing more than a single credential take extra environment variables through env: [...] and nested directive options through options: {...}. Use module to override the Go module path when you need a specific version.

Reaching the domains from other devices. Real certificates are only half of what is needed, because the other devices also have to resolve those names to this machine. Point A records for the domain, or for the wildcard, at this machine's LAN IP in the DNS zone you already control, or add the hosts to your router's DNS. lo1's /etc/hosts management only covers the machine running it.

Contributing

See CONTRIBUTING.md for development setup, commands, and commit conventions.

License

Apache-2.0

About

Your whole system, running locally: every service and the infrastructure behind it, wired together over HTTPS on real local domains, with one command.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages