diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..f523180 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,60 @@ +name: Bug report +description: Something in HomeCloud (server, CLI, console, install) does not work as documented. +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting. If an AWS tool (AWS CLI, SDK, Terraform) fails because an operation or option is missing, use the **AWS compatibility gap** form instead. + **Security problems:** do not file them here; see [SECURITY.md](https://github.com/solinode/homecloud/blob/main/SECURITY.md). + - type: textarea + id: what + attributes: + label: What happened + description: What you did, what you expected, and what happened instead. + validations: + required: true + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Commands, a small Terraform file or script, or console clicks. The smaller the better. + render: shell + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs and error output + description: The error message, and the relevant lines of the `homecloud serve` output. Remove secrets and access keys. + render: text + - type: input + id: version + attributes: + label: HomeCloud version + description: Output of `homecloud version`. + validations: + required: true + - type: dropdown + id: docker + attributes: + label: Docker + options: + - Docker Engine on Linux + - Docker Desktop (macOS) + - Docker Desktop (Windows) + - OrbStack + - Other + validations: + required: true + - type: input + id: os + attributes: + label: Operating system and architecture + placeholder: e.g. Ubuntu 24.04 amd64, macOS 15 arm64 + - type: textarea + id: doctor + attributes: + label: homecloud doctor + description: Output of `homecloud doctor`, if relevant. + render: text diff --git a/.github/ISSUE_TEMPLATE/compatibility_gap.yml b/.github/ISSUE_TEMPLATE/compatibility_gap.yml new file mode 100644 index 0000000..2b9688b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/compatibility_gap.yml @@ -0,0 +1,76 @@ +name: AWS compatibility gap +description: An AWS CLI command, SDK call, Terraform resource or CloudFormation template that works on AWS but not on HomeCloud. +labels: ["aws-api"] +body: + - type: markdown + attributes: + value: | + These reports drive what gets implemented next, so thank you. Check [docs/aws-compat.md](https://github.com/solinode/homecloud/blob/main/docs/aws-compat.md) first: it lists what each service supports and what is known to be missing. + - type: input + id: service + attributes: + label: AWS service and operation + placeholder: e.g. SQS ListQueueTags, aws_dynamodb_table, AWS::ECS::Cluster + validations: + required: true + - type: dropdown + id: tool + attributes: + label: Tool + options: + - AWS CLI + - boto3 / botocore + - AWS SDK for JavaScript + - AWS SDK for Go + - AWS SDK for Java + - Other AWS SDK + - Terraform / OpenTofu + - AWS CDK + - CloudFormation + - Pulumi + - Other + multiple: true + validations: + required: true + - type: input + id: tool-version + attributes: + label: Tool version + placeholder: e.g. aws-cli/2.17.0, hashicorp/aws 5.60.0 + - type: textarea + id: repro + attributes: + label: Request that fails + description: The smallest command, code or configuration that shows it. + render: shell + validations: + required: true + - type: textarea + id: actual + attributes: + label: What HomeCloud returns + description: The error (e.g. `UnknownOperationException`, `InvalidAction`) or the wrong output. For Terraform, `TF_LOG=debug` output around the failing call helps. + render: text + validations: + required: true + - type: textarea + id: expected + attributes: + label: What AWS does + description: The expected response or behavior, with a link to the AWS API reference if you have one. + - type: textarea + id: why + attributes: + label: How it blocks you + description: Is there a workaround? Is this one call in a larger stack (which)? + - type: input + id: version + attributes: + label: HomeCloud version + description: Output of `homecloud version`. + - type: checkboxes + id: contribute + attributes: + label: Contributing + options: + - label: I would like to implement this (see CONTRIBUTING.md, "Making changes"). diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..c9208e9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: Report a security vulnerability + url: https://github.com/solinode/homecloud/security/advisories/new + about: Please report security problems privately, not as public issues. + - name: Questions and ideas + url: https://github.com/solinode/homecloud/discussions + about: Ask how to do something or discuss a larger idea. + - name: Discord + url: https://discord.gg/pemra9uaC9 + about: Chat with other users and the maintainers. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..21516d1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,47 @@ +name: Feature request +description: A new service, console feature, CLI command or improvement. +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + For a missing AWS operation or option, the **AWS compatibility gap** form is quicker. Bigger ideas can start in [Discussions](https://github.com/solinode/homecloud/discussions). + - type: textarea + id: problem + attributes: + label: Problem + description: What are you trying to do, and what gets in the way today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposal + description: What you would like HomeCloud to do. If it mirrors an AWS feature, name it and link the AWS docs. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives and workarounds + - type: dropdown + id: area + attributes: + label: Area + options: + - AWS API compatibility + - Console + - homecloud CLI + - Compute (EC2, ECS, Lambda) + - Networking (VPC, security groups, DNS, load balancers) + - Storage and databases + - Install, upgrade, operations + - Documentation + - Other + multiple: true + - type: checkboxes + id: contribute + attributes: + label: Contributing + options: + - label: I would like to work on this. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..81b4a2e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## What and why + + + +## How it was tested + + + +- [ ] `make test` (or the affected packages: `go test ./internal/svc//`) +- [ ] AWS CLI / boto3 compatibility tests ran (`HC_TEST_PYTHON` set, `aws` on `PATH`) +- [ ] Docker-backed tests ran (not skipped), if the change touches containers +- [ ] Console: `npx tsc --noEmit && npm run build`, if the change touches `console/` + +## Checklist + +- [ ] New routes and AWS operations authorize with the right IAM action and resource ARN +- [ ] Docs updated: `docs/aws-compat.md` (operations, differences from AWS), `docs/architecture.md`, `docs/api.md` (`python3 scripts/gen-api-docs.py`) as needed +- [ ] A line under "Unreleased" in `CHANGELOG.md` for user-visible changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 188eef5..f633a9b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,87 +1,150 @@ # Contributing to HomeCloud -Thank you for your interest in contributing to HomeCloud! Whether you're fixing bugs, adding features, improving documentation, or suggesting ideas, we appreciate your help. - -## How to Get Started - -1. **Fork the Repository** - Create a fork of this repository in your GitHub account to work on your contributions. - -2. **Clone Your Fork** - Clone your forked repository to your local machine. - ```bash - git clone https://github.com//homecloud.git - cd homecloud - ``` - -3. **Create a Branch** - Create a new branch for your changes. Use a descriptive name for the branch. - ```bash - git checkout -b feature/my-new-feature - ``` - -4. **Make Changes** - Implement your changes or fixes. Ensure the code adheres to the coding standards outlined below. - -5. **Test Your Changes** - You need Go 1.23+, Node.js 20+ and Docker. - ```bash - make test # Go unit tests - cd cli && go run . serve # run the server (API + console on :8080) - ./scripts/smoke.sh # end-to-end check of every service against the running server - cd console && NEXT_PUBLIC_API_URL=http://127.0.0.1:8080 npm run dev # console with hot reload - ``` - If you add or change API routes, regenerate the reference with `python3 scripts/gen-api-docs.py`. - -6. **Commit Your Changes** - Write clear and concise commit messages. - ```bash - git add . - git commit -m "Add feature: my-new-feature" - ``` - -7. **Push to Your Fork** - Push your changes to your forked repository. - ```bash - git push origin feature/my-new-feature - ``` - -8. **Create a Pull Request (PR)** - Submit a pull request to the main repository. Include a clear description of the changes you've made and why they are important. - -## Guidelines - -### Code of Conduct - -By participating in this project, you agree to abide by our Code of Conduct. - -### Coding Standards - -- Follow the conventions of the tech stack. -- Write clean, modular, and well-documented code. -- Ensure backward compatibility wherever possible. -- A new service is a package in `cli/internal/svc/` with a `Routes(*httpx.Router)` method, wired in `cli/internal/server/server.go`. Every route declares its IAM action and, when it acts on one resource, that resource's ARN (`httpx.Res(...)`, or `httpx.Deferred()` plus `c.Authorize` in the handler). The server refuses to start otherwise. -- Anything that delivers to another resource (a rule target, a subscription, a trigger) must check the caller's permission on that resource when it is configured. +Thanks for helping. Bug reports, AWS compatibility gaps, docs fixes and code are all welcome. This page +gets you from a fresh clone to a tested pull request. + +By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Pull requests need a signed +[Contributor License Agreement](CLA.md); the CLA bot asks you on your first PR. Security problems go +through [SECURITY.md](SECURITY.md), not public issues. + +## Find something to work on + +- **[Good first issues](https://github.com/solinode/homecloud/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)**: + small, well-scoped tasks with file pointers and acceptance criteria. +- **[Help wanted](https://github.com/solinode/homecloud/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** + and the [`aws-api`](https://github.com/solinode/homecloud/issues?q=is%3Aissue+is%3Aopen+label%3Aaws-api) label. +- **Compatibility gaps you hit yourself.** If your Terraform, CLI or SDK code fails against HomeCloud, + open a [compatibility gap](https://github.com/solinode/homecloud/issues/new?template=compatibility_gap.yml) + issue, then consider fixing it. [docs/aws-compat.md](docs/aws-compat.md) lists what each service does + not support yet. + +Comment on an issue before starting larger work so nobody duplicates it. Ask on +[Discord](https://discord.gg/pemra9uaC9) or in [Discussions](https://github.com/solinode/homecloud/discussions) +if anything is unclear. + +## Prerequisites + +| Tool | Needed for | +| --- | --- | +| Go 1.25+ (see `cli/go.mod`) | the server and CLI | +| Docker: Docker Engine, Docker Desktop or OrbStack | running HomeCloud and the Docker-backed tests | +| Node.js 22+ and npm | the web console (optional if you only touch Go) | +| AWS CLI v2 | AWS compatibility tests (skipped without it) | +| Python 3 with `boto3`, `cryptography`, `pycognito` | boto3 compatibility tests (skipped without it) | +| Terraform or OpenTofu | opt-in Terraform tests | + +```bash +pip install boto3 cryptography pycognito # what CI installs +``` + +## Repository layout + +``` +cli/ Go module: server + CLI, one binary + cmd/ CLI commands (`homecloud ...`, `serve`, `configure`, ...) + internal/server wires every service into one HTTP server + internal/svc/ one package per service (ec2, s3, lambda, sqs, ...); aws*.go files hold the AWS protocol handlers + internal/awsapi AWS protocols: SigV4, awsJson, awsQuery, REST XML/JSON + internal/awsapi/awstest test harness that drives the real AWS CLI and boto3 + internal/httpx native API routing, IAM checks, errors + internal/runtime Docker engine wrapper + internal/store persistent state + internal/web embeds the built console +console/ Next.js web console (static export, embedded into the binary) +docs/ user docs, AWS compatibility, architecture, designs +examples/terraform/ end-to-end Terraform example +scripts/ install scripts, smoke test, API doc generator +pages/ landing page and demo console (homecloud.pages.dev) +``` + +## Build and run + +```bash +git clone https://github.com//homecloud.git && cd homecloud +make build # Go only: bin/homecloud, console shows a placeholder page +make # console + binary (needs Node.js) +./bin/homecloud serve # API and console on http://127.0.0.1:8080 +``` + +For console work, run the API and the Next.js dev server side by side: + +```bash +cd cli && go run . serve +cd console && npm ci && NEXT_PUBLIC_API_URL=http://127.0.0.1:8080 npm run dev # http://localhost:3000 +``` + +`make demo` builds the static demo console (sample data, no server) into `pages/demo/`. + +To try your build without touching your normal installation, give it its own data directory: +`./bin/homecloud serve --data-dir /tmp/hc-dev` (only one HomeCloud installation can own a Docker host +at a time, so stop the other one first). + +## Run the tests + +```bash +make test # cd cli && go test ./... +make vet +cd cli && go test ./internal/svc/sqs/ # one package +cd cli && go test -race -run TestFIFO ./internal/svc/sqs/ +``` + +Many tests **skip silently** when a tool is missing. Before trusting a green run, make sure the ones that +matter for your change actually ran (`go test -v ./internal/svc// 2>&1 | grep -i skip`). + +**Docker.** Tests that start containers connect to Docker through the default socket and skip when it is +unreachable. On macOS the default `/var/run/docker.sock` often does not exist, so point `DOCKER_HOST` at +your engine: + +```bash +export DOCKER_HOST=unix://$HOME/.orbstack/run/docker.sock # OrbStack +export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock # Docker Desktop (macOS) +docker info >/dev/null && echo ok # check it works +``` + +If Docker tests skip with "no free 10.88-119.0.0/16 range", earlier runs leaked networks: list them with +`docker network ls --filter label=homecloud.account` and remove the ones labelled `hctest-*`. + +**AWS tools.** The compatibility tests run the real tools against an in-process endpoint: + +| Variable | Meaning | +| --- | --- | +| `HC_TEST_PYTHON` | Python interpreter with boto3 (default `python3`); e.g. `HC_TEST_PYTHON=$PWD/.venv/bin/python` | +| `HC_TEST_AWS` | path to the `aws` CLI (default: `aws` on `PATH`) | +| `HC_TEST_TERRAFORM` | set to run the Terraform/OpenTofu tests (they download the AWS provider; set `TF_PLUGIN_CACHE_DIR` to reuse it) | +| `HC_TEST_NODE_PATH` | a `node_modules` directory with `amazon-cognito-identity-js`, for the Cognito SRP test in Node.js | + +**End to end.** With a server running, `./scripts/smoke.sh` exercises every service through the CLI and +cleans up after itself (`HC=./bin/homecloud ./scripts/smoke.sh` to choose the binary). CI runs it on Linux. + +**Console.** `cd console && npx tsc --noEmit && npm run build`. + +CI (`.github/workflows/ci.yml`) runs `go vet`, `go test -race`, the console build and the smoke test on +Linux. It skips changes that only touch Markdown, `docs/` or `pages/`. + +## Making changes + +- **A new AWS operation** goes in the service's `aws*.go` file and shares logic with the native handler. + Read [Adding operations](docs/aws-compat.md#adding-operations-for-contributors) first. Always call + `q.Authorize` with the IAM action and resource ARN before acting, and test it with the AWS CLI or boto3 + through `awstest` (look at the service's existing `aws_test.go`). +- **A new native route** declares its IAM action and, when it acts on one resource, that resource's ARN + (`httpx.Res(...)`, or `httpx.Deferred()` plus `c.Authorize` in the handler); the server refuses to start + otherwise. Regenerate the API reference with `python3 scripts/gen-api-docs.py`. +- **A new service** is a package in `cli/internal/svc/` with a `Routes(*httpx.Router)` method, wired in + `cli/internal/server/server.go`. +- Anything that delivers to another resource (a rule target, a subscription, a trigger) must check the + caller's permission on that resource when it is configured. - Docker objects must carry `runtime.Labels(...)` so HomeCloud never touches containers it did not create. - -### Issues and Discussions - -- Browse existing Issues before opening a new one to avoid duplicates. -- Use the appropriate labels for categorization when creating an issue. - -### Commit Messages - -- Use meaningful and descriptive commit messages. -- Format: `type(scope): description` -- Examples: - - `fix(storage): resolve upload bug` - - `feat(dashboard): add bucket creation UI` - -## Need Help? - -If you’re stuck or need clarification, feel free to: - -- Open a [Discussion](https://github.com/solinode/homecloud/discussions). -- Reach out on [Discord](https://discord.gg/pemra9uaC9). - -We’re excited to have you on board. Let’s build something great together! \ No newline at end of file +- Update the docs with the behavior: [docs/aws-compat.md](docs/aws-compat.md) for AWS operations and + differences, [docs/architecture.md](docs/architecture.md) for how things work, and a line under + "Unreleased" in [CHANGELOG.md](CHANGELOG.md) for anything a user would notice. +- Run `gofmt` (or `go vet`) before committing. + +## Commits and pull requests + +- Branch from `main`; keep a pull request to one topic. +- Write commit messages as a plain sentence saying what changed and, if not obvious, why + (`SQS GetQueueAttributes returns RedriveAllowPolicy`). Reference issues with `#123`. +- Fill in the pull request template: what changed, how you tested it (which tests ran, not skipped), and the + docs you updated. +- A maintainer reviews; expect questions about AWS behavior, since matching it closely is the point. diff --git a/Makefile b/Makefile index 846c027..95db01a 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# HomeCloud build. Requires Go 1.23+ and, for the console, Node.js 20+. +# HomeCloud build. Requires Go 1.25+ (cli/go.mod) and, for the console, Node.js 22+. VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev) COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown) LDFLAGS := -s -w -X github.com/homecloudhq/homecloud/cli/cmd.Version=$(VERSION) -X github.com/homecloudhq/homecloud/cli/cmd.Commit=$(COMMIT) diff --git a/README.md b/README.md index c598f3d..b53e537 100644 --- a/README.md +++ b/README.md @@ -1,278 +1,208 @@ -# ☁️ HomeCloud — The Cloud, Owned by You +# HomeCloud -

- HomeCloud: your own AWS, on your hardware -

+**A self-hosted, AWS-compatible cloud in one binary: point your real Terraform, AWS CLI and SDK code at it, and it runs on real containers on your machine.**

- Website · - Live demo · - Quick start · + Live demo console · + Quick start · AWS compatibility · - Architecture · + vs. LocalStack, moto, MinIO… · Discord

-**[Try the live demo console](https://homecloud.pages.dev/demo/)** — click through every service in your browser, no install needed (sample data, runs entirely client-side). - -**An open-source, self-hosted cloud platform.** HomeCloud runs AWS-style services (compute, object storage, managed databases, serverless functions, queues, pub/sub, key-value tables, networking, identity, monitoring) on your own hardware, from one binary, managed through a web console, a CLI and a REST API. - -**Speaks AWS.** The AWS CLI, the AWS SDKs and Terraform work against HomeCloud unchanged: point `AWS_ENDPOINT_URL` at it and use a HomeCloud access key. IAM policies, roles and temporary credentials are enforced exactly as in the console. - -No third parties. No vendor lock-in. No surprise billing. - -> 🛡 Built with privacy, transparency, and sovereignty at its core. - -#### Support Partners - -

- - Tailscale - -

- -

- - Coderabbit - -

- ---- +- **Your AWS code, unchanged.** HomeCloud speaks the AWS wire protocols (SigV4, awsJson, awsQuery, REST). Set `AWS_ENDPOINT_URL` and the AWS CLI, boto3 and the Terraform AWS provider work against it, with IAM policies enforced as on AWS. +- **Real compute, not mocks.** Lambda runs on AWS's official runtime images, RDS is a real PostgreSQL/MySQL/MariaDB, S3 is MinIO, EC2 instances are containers you can shell into, load balancers are nginx, security groups are iptables rules. Your integration tests hit the same kind of thing production does. +- **See what happened.** A web console modeled on AWS's, CloudWatch logs and metrics for every resource, and a CloudTrail record of every AWS API call, so a failed test run can be inspected instead of guessed at. -## 🖥️ The console - -A web console modeled on the one you know, with a page for every service. It is built into the binary: run `homecloud serve` and open http://127.0.0.1:8080. +Built for **developers who want a real AWS-compatible target for local development and CI**. It also suits **college labs** teaching AWS without accounts or bills, and **small teams and homelabs** that want AWS tooling on their own hardware.

- Console home: every service at a glance + HomeCloud console home

- - - - - - - - - - - - - -
EC2 instances

EC2: instances running as containers in your VPCs

Lambda function

Lambda: functions with roles, versions, aliases and an in-browser editor

S3 bucket

S3: buckets and objects, uploads, presigned links, websites

IAM role

IAM: users, roles, AWS-managed and custom policies

DynamoDB table

DynamoDB: tables, queries and an item editor

CloudWatch

CloudWatch: metrics for every resource, alarms and logs

- ---- - -## 🧰 Services - -| Service | AWS equivalent | What you get | -| --- | --- | --- | -| **Compute** | EC2, EBS, AMIs | Instances with CPU/memory limits from `t3.nano` to `r5.large`, 10 base images (Ubuntu, Debian, Amazon Linux, Rocky, Fedora, Alpine, …), user data, key pairs, start/stop/reboot/resize, volumes and snapshots, capture an instance as a new image, run-command, a shell in the browser, and an instance metadata service (IMDSv1/v2) that hands role credentials to SDKs inside instances | -| **Auto Scaling** | EC2 Auto Scaling | Groups that keep a desired number of instances across subnets, replace unhealthy ones, register them with load balancers and scale on CPU or memory targets | -| **Shared files** | EFS | File systems that any number of instances mount at the same time | -| **Containers** | ECS (Fargate), ECR | Versioned task definitions with secrets injected from Secrets Manager, services that keep N tasks running with rolling deployments and load-balancer registration, one-off tasks, and a private image registry you `docker push` to | -| **Networking** | VPC, ELB | VPCs and subnets with real private IP addressing, private DNS (`ip-10-88-0-4.internal`, `mydb.rds.internal`), security groups that filter traffic between resources (ingress and egress, by CIDR or by referenced group) and decide which ports are published; application load balancers with HTTP/HTTPS listeners, HTTP→HTTPS redirects, path/host routing rules, target groups and health checks | -| **DNS** | Route 53 | Public and private hosted zones (A, AAAA, CNAME, TXT, MX, SRV, CAA, NS, PTR), alias records that follow instances, tasks, databases and load balancers; a resolver at each VPC's `.2` address and a LAN-facing DNS port | -| **Certificates** | ACM | A private certificate authority that issues TLS certificates for your domains and IPs, import of Let's Encrypt or other certificates, renewal, and HTTPS on load balancers | -| **Object storage** | S3 | Buckets, folders, uploads/downloads, versioning, public-read access, lifecycle expiry, presigned URLs, static website hosting, and a fully S3-compatible endpoint for AWS SDKs and `aws` CLI | -| **Databases** | RDS, ElastiCache, DocumentDB | PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Valkey, Memcached with generated credentials in Secrets Manager, snapshots and restore, daily automated backups, resizing, password rotation and a query editor | -| **Serverless** | Lambda, API Gateway | Functions on AWS's official runtime images (Python, Node.js, Java, Ruby, .NET, Go/Rust custom runtimes, container images) with warm environments, execution roles, versions and aliases, layers, async invocation with retries and destinations, reserved concurrency; function URLs; HTTP APIs with JWT authorizers; SQS and DynamoDB stream triggers | -| **Queues** | SQS | Standard and FIFO queues, visibility timeouts, delays, long polling, dead-letter queues with redrive, batches | -| **Pub/sub** | SNS | Standard and FIFO topics fanning out to queues, functions and confirmed HTTP(S) endpoints, signed messages, raw delivery, full filter-policy syntax | -| **Key-value** | DynamoDB | Typed items with the full condition/update/projection expression language, GSIs and LSIs, batches, transactions, PartiQL, TTL and streams | -| **Workflows** | Step Functions | State machines in Amazon States Language: Task (Lambda, SQS, SNS), Choice, Wait, Parallel, Map, Pass, Succeed, Fail, with Retry/Catch, JSONPath input/output processing, intrinsic functions and a full execution history | -| **Events** | EventBridge, Scheduler | Event buses with the full pattern syntax, input transformers, retries and DLQs; schedules with `at()`/`rate()`/`cron()` and time zones | -| **Identity** | IAM, STS | Users, groups, roles with trust policies, AWS-managed and custom policies (with versions, conditions and permissions boundaries), instance profiles, access keys, temporary credentials, console passwords, a policy simulator | -| **App identity** | Cognito | User pools with sign-up, sign-in, refresh tokens, forced password changes, groups and global sign-out; RS256 JWTs with a JWKS endpoint; API Gateway routes can require them | -| **Secrets & keys** | Secrets Manager, KMS, SSM Parameter Store | Versioned secrets with staging labels and Lambda rotation; symmetric, RSA, ECC and HMAC keys with policies, grants and rotation; hierarchical parameters with SecureString values, versions and labels | -| **Monitoring** | CloudWatch | Per-resource metrics, custom metrics with metric math, alarms that notify SNS topics or webhooks, log groups with filter patterns, Logs Insights queries and subscription filters | -| **Infrastructure as code** | CloudFormation | YAML/JSON stack templates for 30 resource types across every service, with parameters, outputs, `!Ref`/`!GetAtt`/`!Sub`/`!Join`, dependency ordering, readiness waits, rollback, updates and ordered deletion | -| **Audit** | CloudTrail | A record of every change and every denied request, with who, what, when and from where | - -Everything runs as containers on Docker, labelled so HomeCloud never touches containers it didn't create. See **[docs/architecture.md](docs/architecture.md)** for how each service is built, **[docs/aws-compat.md](docs/aws-compat.md)** for the AWS APIs it speaks and **[docs/api.md](docs/api.md)** for the native API reference. - --- -## 🚀 Quick start +## Quick start -You need **Docker** (Docker Engine on Linux, or Docker Desktop / OrbStack on macOS and Windows). - -### Install - -**Linux / macOS** +You need **Docker** (Docker Engine on Linux, Docker Desktop or OrbStack on macOS and Windows). ```bash -curl -fsSL https://homecloud.pages.dev/scripts/install.sh | sh +curl -fsSL https://homecloud.pages.dev/scripts/install.sh | sh # Linux / macOS +homecloud serve ``` -**Windows (PowerShell)** +
Windows (PowerShell) ```powershell irm https://homecloud.pages.dev/scripts/install.ps1 | iex -``` - -Running it on a VPS or home server? See **[Install on a server](docs/install-server.md)** (system service, TLS, firewall, backups). - -Or build from source with Go 1.25+ and Node.js 22+: `make` (the binary lands in `bin/homecloud`). - -### Run - -```bash homecloud serve ``` +
-On first start HomeCloud creates your account, prints the **root console password** once, and writes CLI credentials to `~/.homecloud/credentials`. Open **http://127.0.0.1:8080** and sign in as `root`. +On first start HomeCloud creates your account, prints the **root console password** once, and writes CLI credentials to `~/.homecloud/credentials`. Open **http://127.0.0.1:8080** and sign in as `root`. The first start pulls container images (MinIO, and later the engines you use), so it takes longer than the next ones. -To reach it from other machines, bind to your LAN or Tailscale address (add `--tls-self-signed`, or `--tls-cert`/`--tls-key`, to serve HTTPS): +Then, in another terminal, use your normal AWS tools: ```bash -homecloud serve --addr 0.0.0.0:8080 --public-host homelab.tailnet.ts.net --tls-self-signed +eval "$(homecloud aws-env)" # sets AWS_ENDPOINT_URL, access keys and region +aws sts get-caller-identity +aws s3 mb s3://demo && echo hi | aws s3 cp - s3://demo/hello.txt +aws sqs create-queue --queue-name jobs ``` -### Use it from the CLI + +> **Docker image:** a `ghcr.io/solinode/homecloud` image, so HomeCloud can start with a single `docker run`, is being worked on. Until it is released, use the install script above. -```bash -# Compute: a web server whose port 80 is published -homecloud vpc create-sg web && homecloud vpc allow sg-xxxx 80 -homecloud ec2 run --name web --image ami-nginx --sg sg-xxxx -homecloud ec2 ssh i-xxxx - -# Storage -homecloud s3 mb s3://photos -homecloud s3 cp ./beach.jpg s3://photos/2025/ -homecloud s3 presign s3://photos/2025/beach.jpg - -# A PostgreSQL database; the password lives in Secrets Manager -homecloud rds create orders-db --engine postgres --public -homecloud rds query orders-db "select version()" -homecloud rds password orders-db - -# Serverless: a function behind an HTTP API, fed by a queue -homecloud lambda create resize --runtime python3.12 --code ./resize -homecloud lambda url resize -homecloud sqs create jobs --dlq jobs-dlq -homecloud lambda trigger resize jobs +Other ways to install: build from source with Go 1.25+ and Node.js 22+ (`make`, binary in `bin/homecloud`), or follow **[Install on a server](docs/install-server.md)** for a VPS or home server (system service, TLS, firewall, backups). -# Schedules and events -homecloud events schedule nightly 'cron(0 3 ? * * *)' --target arn:aws:lambda:us-east-1::function:resize +### In CI -# Containers behind a load balancer -docker tag myapi localhost:5500/myapi:1 && docker push localhost:5500/myapi:1 -homecloud elb create-target-group api-tg --port 8000 -homecloud elb create web --listen 80=api-tg -homecloud ecs register api --image localhost:5500/myapi:1 --port 8000 --secret DB_PASS=prod/db:password -homecloud ecs create-service api api --count 3 --target-group api-tg +HomeCloud's own end-to-end job runs it on a stock GitHub Actions runner. The same pattern works for your tests: -# Infrastructure as code (see docs/examples/pipeline.yaml) -homecloud cfn create pipeline docs/examples/pipeline.yaml -p Env=dev -homecloud cfn delete pipeline - -# Anything else -homecloud api GET /api/v1/cloudwatch/alarms +```bash +curl -fsSL https://homecloud.pages.dev/scripts/install.sh | sh +nohup homecloud serve > homecloud.log 2>&1 & +for i in $(seq 1 60); do curl -fsS localhost:8080/api/v1/health && break; sleep 2; done +eval "$(homecloud aws-env)" +# ... terraform apply / pytest / your test suite ... ``` -Run `homecloud --help` or `homecloud --help` for every command. +S3 starts in the background on first boot; if your tests use S3 right away, wait for `s3: MinIO ready` in the log (see [`.github/workflows/ci.yml`](.github/workflows/ci.yml)). -### Use it from AWS tools +--- -HomeCloud speaks the AWS protocols on its API port, so the AWS CLI, SDKs (boto3, JS, Go, Java) and Terraform work unchanged with HomeCloud credentials and IAM: +## Works with -```bash -eval "$(homecloud aws-env)" # AWS_ENDPOINT_URL, keys and region -aws s3 ls -aws lambda invoke --function-name hello out.json -``` +| Tool | Status | +| --- | --- | +| **AWS CLI v2** | Tested: the compatibility test suite drives the real `aws` CLI in CI | +| **boto3** (Python SDK) | Tested: the compatibility test suite runs boto3 in CI, including Cognito SRP sign-in through pycognito | +| **Terraform / OpenTofu** (`hashicorp/aws` provider) | Tested: opt-in Terraform tests in the suite (IAM, S3, Route 53, CloudFormation and more; `HC_TEST_TERRAFORM=1`), and [`examples/terraform/shop`](examples/terraform/shop/README.md) applies, re-plans clean and destroys on a fresh install | +| **CloudFormation** (`aws cloudformation deploy`) | Tested: stacks, change sets and the boto3 waiters ([details](docs/aws-compat.md#cloudformation)) | +| **AWS CDK** | Partly: CDK-synthesized templates deploy through CloudFormation change sets; `cdk bootstrap` / `cdk deploy` end to end is not yet verified | +| **Other AWS SDKs** (JavaScript, Go, Java, …) and **Pulumi** | Expected to work (same protocols and SigV4), not yet covered by tests. Reports welcome | -See [docs/aws-compat.md](docs/aws-compat.md) for the supported services and operations. +Run `homecloud aws-env` to get the environment variables. For Terraform, point the provider's `endpoints {}` block at HomeCloud and use `s3_use_path_style = true`; the [shop example](examples/terraform/shop/README.md) shows a complete provider block. -### Run it as a service, back it up, upgrade it +--- -```bash -homecloud service install # launchd (macOS) or systemd (Linux) -homecloud backup -o backup.tar.gz # state, keys and every Docker volume -homecloud restore backup.tar.gz # with the server stopped -homecloud upgrade # verified update from GitHub releases -``` +## Services + +"AWS API" means the AWS CLI, SDKs and Terraform can manage it; every service is also in the console, the `homecloud` CLI and the [native REST API](docs/api.md). The notes name the main gaps; [docs/aws-compat.md](docs/aws-compat.md) lists operations and differences per service. + +| Service | AWS equivalent | Status | Notes | +| --- | --- | --- | --- | +| Compute | EC2, EBS, AMIs | AWS API | Instances are **containers**, not VMs (VM-backed instances are in progress, [#3](https://github.com/solinode/homecloud/issues/3)). Key pairs, user data, volumes, snapshots, launch templates, Elastic IPs (records only), IMDSv1/v2, browser shell | +| Auto Scaling | EC2 Auto Scaling | AWS API | Target tracking on CPU; scheduled actions and lifecycle hooks are not implemented | +| Networking | VPC, security groups | AWS API | Security groups enforced inside the VPC; network ACLs recorded, not enforced; no peering; IPv4 only | +| Load balancing | ELB v2 | AWS API | Application load balancers (HTTP/HTTPS, path/host rules). No network load balancers | +| DNS | Route 53 | AWS API | Public and private zones served by CoreDNS; no routing policies or health checks | +| Certificates | ACM | AWS API | Issued from HomeCloud's private CA, not a public one | +| Object storage | S3 | AWS API | MinIO underneath; versioning, lifecycle expiry, presigned URLs, bucket policies, websites | +| Shared files | EFS | AWS API | Docker volumes mounted into instances and tasks; no NFS endpoint | +| Containers | ECS (Fargate), ECR | AWS API | One container per task definition | +| Databases | RDS | AWS API | PostgreSQL, MySQL, MariaDB; no Multi-AZ, read replicas or Aurora | +| Caches | ElastiCache | AWS API | Redis, Valkey, Memcached; one node per cluster, no TLS | +| Document DB | DocumentDB-style MongoDB | Native API only | MongoDB through the console, CLI and native API | +| Functions | Lambda | AWS API | AWS runtime images, versions, aliases, layers, async invoke, SQS and DynamoDB stream triggers, function URLs | +| HTTP APIs | API Gateway v2 | AWS API | HTTP APIs with Lambda/HTTP proxy and JWT authorizers; REST and WebSocket APIs are not supported | +| Queues | SQS | AWS API | Standard and FIFO, DLQs and redrive | +| Pub/sub | SNS | AWS API | SQS, Lambda and HTTP(S) subscriptions with filter policies; e-mail and SMS messages are written to the server log, not sent | +| Key-value | DynamoDB | AWS API | Expressions, GSIs/LSIs, transactions, PartiQL, TTL, streams | +| Workflows | Step Functions | AWS API | Lambda, SQS and SNS tasks; no activities | +| Events | EventBridge, Scheduler | AWS API | Buses, rules, schedules; no archives or replays | +| Identity | IAM, STS | AWS API | Policies with conditions, roles, temporary credentials, permissions boundaries, simulator | +| App identity | Cognito user pools | AWS API | SRP and password sign-in, JWTs; no MFA or hosted UI; codes go to the server log instead of e-mail/SMS | +| Secrets and keys | Secrets Manager, KMS, SSM Parameter Store | AWS API | Single region, so replication and multi-Region replicas are refused | +| Monitoring | CloudWatch, CloudWatch Logs | AWS API | Metrics, metric math, alarms, Logs Insights; anomaly bands are a statistical approximation, not AWS's model | +| Infrastructure as code | CloudFormation | AWS API | Change sets, updates with rollback; no nested stacks, custom resources or `AWS::Serverless` | +| Audit | CloudTrail | AWS API | Every AWS-protocol call and every mutating or denied native call; trails deliver to S3 | + +Overall limits: HomeCloud runs on **one Docker host** and serves **one region** (`us-east-1`) and one account. Multi-node clusters are a [design](docs/design/multi-node.md) ([#55](https://github.com/solinode/homecloud/issues/55)), not a feature. --- -## 🗺️ Roadmap +## The console -* ✅ **Phase 1:** Core cloud stack: compute, storage, networking, web console, CLI and API -* ✅ **Phase 2:** Serverless and event-driven services: Lambda, API Gateway, SQS, SNS, EventBridge, DynamoDB -* ✅ **Phase 3 (first cut):** Observability and governance: CloudWatch metrics/logs/alarms, CloudTrail, IAM, Secrets Manager -* ✅ **Containers:** ECS services and tasks, ECR registry, load balancers, shared file systems -* ✅ **Workflows:** Step Functions -* ✅ **Infrastructure as code:** CloudFormation-style stacks -* ✅ **AWS compatibility:** the AWS CLI, SDKs and Terraform work against HomeCloud for IAM/STS, EC2/VPC, S3, Lambda, DynamoDB, SQS, SNS, Secrets Manager, SSM, KMS, CloudWatch, EventBridge, Step Functions, Elastic Load Balancing, Auto Scaling, ECS and ECR -* 🔄 **Next:** AWS APIs for RDS, API Gateway, Route 53, ACM, EFS, ElastiCache and CloudFormation; stricter security groups and resource policies; VM-backed instances (QEMU/KVM); multi-node clusters -* 🔄 **Phase 4:** Edge compute and hardware integrations +Built into the binary: run `homecloud serve` and open http://127.0.0.1:8080, or **[try the demo](https://homecloud.pages.dev/demo/)** in your browser (sample data, runs entirely client-side, nothing to install). -Designs for the two largest open items: **[multi-node clusters](docs/design/multi-node.md)** ([#55](https://github.com/solinode/homecloud/issues/55)) and **[edge compute and hardware integrations](docs/design/edge.md)** ([#56](https://github.com/solinode/homecloud/issues/56)). - -📍 **[See the open issues](https://github.com/solinode/homecloud/issues)** for everything planned, with a checklist per item. + + + + + + + + + + + + + +
EC2 instances

EC2: instances in your VPCs

Lambda function

Lambda: functions, versions, aliases, in-browser editor

S3 bucket

S3: buckets, objects, presigned links

IAM role

IAM: users, roles and policies

DynamoDB table

DynamoDB: tables, queries, item editor

CloudWatch

CloudWatch: metrics, alarms and logs

--- -## 🧑‍💻 Development +## The `homecloud` CLI -``` -cli/ Go server + CLI (single binary) - cmd/ CLI commands - internal/server wires services into one HTTP API - internal/svc/ one package per service (ec2, s3, rds, lambda, ...) - internal/httpx native API routing, IAM checks, errors - internal/awsapi AWS protocols: SigV4, awsJson, awsQuery, REST - internal/system backup and restore - internal/runtime Docker engine wrapper - internal/store persistent state -console/ Next.js web console (static export, embedded into the binary) -docs/ architecture and API reference -``` +Besides the AWS tools, HomeCloud has its own shorter CLI for every service: ```bash -make test # Go tests (AWS CLI/boto3 tests run when installed) -cd cli && go run . serve # API on :8080 -cd console && NEXT_PUBLIC_API_URL=http://127.0.0.1:8080 npm run dev # console on :3000 -make release # cross-compiled archives for 6 platforms in dist/ +homecloud ec2 run --name web --image ami-nginx --sg sg-xxxx # an instance +homecloud rds create orders-db --engine postgres --public # a database, password in Secrets Manager +homecloud lambda create resize --runtime python3.12 --code ./resize +homecloud sqs create jobs --dlq jobs-dlq && homecloud lambda trigger resize jobs +homecloud cfn create pipeline docs/examples/pipeline.yaml -p Env=dev +homecloud api GET /api/v1/cloudwatch/alarms # anything else, raw ``` -Releases are built by GitHub Actions when a `v*` tag is pushed. +Run `homecloud --help` or `homecloud --help` for every command. Operations: `homecloud service install` (launchd or systemd), `homecloud backup` / `restore`, `homecloud upgrade`, `homecloud doctor`. + +To reach the server from other machines, bind it to a LAN or Tailscale address with TLS: + +```bash +homecloud serve --addr 0.0.0.0:8080 --public-host homelab.tailnet.ts.net --tls-self-signed +``` --- -## 💸 Sustainability & Support +## Documentation -HomeCloud is a community project, currently unfunded and maintained by volunteers. +- [AWS compatibility](docs/aws-compat.md): supported operations per service, IAM behavior, differences from AWS +- [Comparison](docs/comparison.md) with LocalStack, moto, MinIO, OpenStack and the AWS free tier +- [Architecture](docs/architecture.md): how each service is built, where state lives, limits +- [Install on a server](docs/install-server.md): VPS or home server, TLS, firewall, backups, upgrades +- [Native API reference](docs/api.md) +- [Security audit, October 2026](docs/security-audit-2026-10.md) and the [security policy](SECURITY.md) +- Designs: [multi-node clusters](docs/design/multi-node.md), [edge compute](docs/design/edge.md) +- [Changelog](CHANGELOG.md) -### 💛 Ways to Support +## Security -* [ ] Sponsor development via GitHub Sponsors / Open Collective (Coming Soon) -* [ ] Contribute infrastructure, bugfixes, or UX improvements -* [ ] Share HomeCloud with your communities! +HomeCloud needs the Docker socket, which is root-equivalent on the host: treat HomeCloud administrators as host administrators. The API binds to `127.0.0.1` by default. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md). ---- +## Roadmap -## 🤝 Get Involved +- **In progress:** VM-backed instances with QEMU/KVM ([#3](https://github.com/solinode/homecloud/issues/3)), a container image for one-command starts +- **Planned:** multi-node clusters ([#55](https://github.com/solinode/homecloud/issues/55)), edge compute and hardware integrations ([#56](https://github.com/solinode/homecloud/issues/56)) -We’re building HomeCloud for the community, and we’d love for you to join us: +See the [open issues](https://github.com/solinode/homecloud/issues) for everything planned. -💬 **[Join the Discord Community](https://discord.gg/pemra9uaC9)**: connect, discuss, and collaborate. -🛠️ **Contribute Code**: check out **Issues** and **Pull Requests** to get started. -📣 **Share Feedback**: help shape what HomeCloud becomes. +## Contributing -🔹 **By contributing, you agree to our** [**Contributor License Agreement (CLA)**](./CLA.md). +Start with **[CONTRIBUTING.md](CONTRIBUTING.md)**: how to build, run the tests and pick up a [good first issue](https://github.com/solinode/homecloud/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). Missing an AWS operation your code needs? Open a [compatibility gap](https://github.com/solinode/homecloud/issues/new?template=compatibility_gap.yml) issue. By contributing you agree to the [Contributor License Agreement](CLA.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). ---- +Chat with us on **[Discord](https://discord.gg/pemra9uaC9)**. -## 🛡 License +### Support partners -HomeCloud is released under **GNU AGPL-3.0**: open, transparent, and libre. -If you deploy or modify it publicly, share your changes too. +

+ Tailscale +    + CodeRabbit +

---- +## License -## ⚡ HomeCloud: The Cloud, On Your Terms. +[GNU AGPL-3.0](LICENSE). If you run a modified HomeCloud as a service for others, share your changes. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2060c34 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,56 @@ +# Security policy + +## Supported versions + +HomeCloud is before 1.0. Security fixes go into the latest release only; there are no backports to +older minor versions. + +| Version | Supported | +| --- | --- | +| Latest release (see [Releases](https://github.com/solinode/homecloud/releases)) | Yes | +| `main` | Yes, fixes land here first | +| Older releases | No: upgrade with `homecloud upgrade` | + +## Reporting a vulnerability + +Please **do not open a public issue, pull request or Discord message** for a security problem. + +Report it privately through GitHub's security advisories: +**[Report a vulnerability](https://github.com/solinode/homecloud/security/advisories/new)** +(Security tab, "Report a vulnerability"). Only the maintainers can see the report. + +A useful report includes: + +- the HomeCloud version (`homecloud version`) and how it is run (OS, Docker Engine / Docker Desktop / + OrbStack, flags such as `--addr`, TLS, a reverse proxy); +- what an attacker needs (network access to the API, an IAM user with which permissions, a function or + instance they control, ...); +- steps to reproduce, ideally an AWS CLI, boto3 or `curl` sequence; +- the impact you expect (privilege escalation, reading another user's data, escaping a container, ...). + +## What to expect + +HomeCloud is maintained by volunteers, so these are goals rather than guarantees: + +- an acknowledgement within a few days; +- an initial assessment (confirmed or not, and severity) after that, discussed in the private advisory; +- a fix in a new release, with a GitHub security advisory and a CHANGELOG entry crediting you unless you + prefer otherwise. We ask that you keep the details private until the fixed release is out. + +## Scope + +In scope: the `homecloud` binary (server, CLI, embedded console), the install scripts, and the release +artifacts. Of particular interest: authentication (SigV4, sessions, unsigned Cognito operations), IAM +authorization and confused-deputy paths between services, SSRF through webhooks and integrations, isolation +between tenants' resources, and anything that reaches the host from inside a function, task or instance. + +Known and accepted behavior is not a vulnerability by itself. In particular: + +- HomeCloud needs the Docker socket, which is root-equivalent on the host. HomeCloud administrators (the root + user and anyone with broad IAM permissions) are host administrators. +- Instances are containers that share the host kernel; they are not a VM boundary. +- The accepted findings of the [October 2026 security audit](docs/security-audit-2026-10.md) (for example + SigV4 replay within the clock-skew window, or RFC 1918 webhook targets being allowed by default). + +The audit report describes the threat model, what was reviewed and what was fixed. Hardening advice for +servers is in [Install on a server](docs/install-server.md#13-security-notes). diff --git a/docs/aws-compat.md b/docs/aws-compat.md index 63ca5e1..44772f1 100644 --- a/docs/aws-compat.md +++ b/docs/aws-compat.md @@ -1,8 +1,10 @@ # Using AWS tools with HomeCloud HomeCloud speaks the AWS wire protocols, so the AWS CLI, the AWS SDKs and tools built on them -(Terraform, CDK, Pulumi, boto3 scripts) work against it. Point them at your HomeCloud endpoint -and use a HomeCloud access key: +work against it. The test suite drives the real AWS CLI, boto3 and Terraform; CloudFormation +(including CDK-synthesized templates) is covered too. Other SDKs and Pulumi use the same +protocols but are not tested yet. Point them at your HomeCloud endpoint and use a HomeCloud +access key: ```bash export AWS_ENDPOINT_URL=http://localhost:8080 # your HomeCloud API address diff --git a/docs/comparison.md b/docs/comparison.md new file mode 100644 index 0000000..b666760 --- /dev/null +++ b/docs/comparison.md @@ -0,0 +1,129 @@ +# How HomeCloud compares + +HomeCloud is one of several ways to run "AWS without AWS". This page tries to be honest about where it +fits, where it is the better choice, and where something else is. Other projects change quickly: check +their current documentation and licensing before deciding, and tell us (an issue or a pull request) if +anything here is out of date. + +## The short version + +- **You want AWS APIs with real compute behind them, a console, and IAM enforced, on your own machine or + server, for free:** HomeCloud. +- **You need the widest possible AWS service coverage for local testing, or services HomeCloud lacks + (Kinesis, EKS, Athena, REST API Gateway, ...):** LocalStack, Pro for most of those. +- **You want fast, in-process mocks for unit tests in Python:** moto. +- **You only need S3-compatible storage, plus Kubernetes for compute:** MinIO and k3s. +- **You need a multi-node private cloud with real VMs, and have people to run it:** OpenStack. +- **You need exactly AWS's behavior:** AWS itself (free tier, or a sandbox account). + +## At a glance + +| | HomeCloud | LocalStack Community | LocalStack Pro | moto (server mode) | MinIO + k3s | OpenStack | AWS free tier | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Speaks AWS APIs | Yes, about 30 services | Yes, core services | Yes, the most services of any emulator | Yes, very broad API surface | S3 only (MinIO) | Its own APIs; S3 through Swift middleware | It is AWS | +| What runs behind the API | Real engines in Docker: Lambda runtime images, PostgreSQL/MySQL/MariaDB, Redis/Valkey, MinIO, nginx, CoreDNS | Emulation; some services start real containers (for example Lambda) | Emulation plus real engines for several services | Mostly in-memory models | Real storage and real Kubernetes | Real VMs, networks, volumes | Real AWS | +| IAM enforcement | On by default, same evaluator for every service | Not enforced | Available, opt-in | Partial | MinIO policies only | Keystone (not IAM) | Yes | +| Web console | Built in, modeled on AWS's | Hosted web app, needs an account | Hosted web app | Basic dashboard | MinIO console, Kubernetes dashboards | Horizon | AWS console | +| Persistence | State on disk by default; backup and restore commands | Ephemeral by default | Persistence and snapshots | In memory | Yes | Yes | Yes | +| Deployment | One Go binary plus Docker | One container | One container plus a licence | Python package or container | Two systems to install and wire | Many services, multi-node | None | +| Multi-node | No (designed, not built) | No | No | No | k3s yes; MinIO distributed mode | Yes | Yes | +| Regions / accounts | One region, one account | Many | Many | Many | n/a | n/a | All | +| Cost and licence | Free, AGPL-3.0 | Free tier; check current terms | Paid subscription | Free, Apache-2.0 | Free (AGPL MinIO, Apache k3s); see MinIO note below | Free, Apache-2.0 | Free within limits, then billed | +| Maturity | Young: first release September 2026 | Mature, large community | Mature, commercial support | Mature, widely used | Mature | Mature | n/a | + +"Yes" for a feature never means "the same as AWS"; every emulator, HomeCloud included, has gaps. HomeCloud's +are listed per service in [aws-compat.md](aws-compat.md) and [architecture.md](architecture.md#limits-and-differences-from-aws). + +## LocalStack (Community and Pro) + +LocalStack is the best-known AWS emulator and the closest comparison. + +**Where HomeCloud is better** + +- **Real workloads by default.** RDS gives you a real PostgreSQL, MySQL or MariaDB; ElastiCache a real Redis + or Valkey; EC2 instances are containers you can SSH into; ECS services sit behind a real load balancer; + security groups really filter traffic between them. With LocalStack Community several of these services + are not available, and with Pro the depth varies per service. +- **IAM is always on.** Every request, from the AWS CLI, the SDKs, Terraform or the console, goes through the + same policy evaluator with resource policies, conditions, permissions boundaries and `iam:PassRole`. Tests + that pass against HomeCloud have at least been checked for the permissions they need. +- **A console in the box.** The web console ships inside the binary and works offline, with metrics, logs + and a CloudTrail audit trail of API calls. +- **Persistent and multi-user.** It is built to be left running for a team or a classroom: users, roles and + access keys, backups, upgrades, TLS, a system service. +- **Fully open source.** Every feature is in the AGPL-3.0 code; there is no paid tier. + +**Where LocalStack is better** + +- **Service coverage.** LocalStack Pro covers far more AWS services and operations than HomeCloud. If your + stack uses Kinesis, EKS, Athena, Glue, OpenSearch, REST API Gateway, WebSocket APIs, AppSync or similar, + HomeCloud does not have them. +- **Multi-region and multi-account** setups work; HomeCloud has one region (`us-east-1`) and one account. +- **Startup and footprint for CI.** A single container that emulates most services in-process is light; + HomeCloud starts real engines (MinIO on first boot, databases and runtimes on demand), which takes longer + and uses more memory. +- **Ecosystem and maturity.** Years of production use, `tflocal`/`cdklocal`/`awslocal` wrappers, testing + integrations, extensive docs and commercial support. HomeCloud is young. + +## moto (server mode) + +moto is a Python library that mocks AWS; `moto_server` exposes the same mocks over HTTP. + +**HomeCloud is better** when the test needs something to actually run: a Lambda function on the real runtime, +a database you can query, a queue that triggers a function, traffic through a load balancer. It is also a +long-running server with a console and persistent state, which moto is not meant to be. + +**moto is better** for fast, isolated unit tests: it starts in milliseconds, resets between tests, runs +in-process in Python (`@mock_aws`) and models a very wide range of services and operations. For a unit test +of code that calls `put_item`, moto is the simpler tool. + +## MinIO, optionally with k3s + +MinIO is an excellent S3-compatible object store (HomeCloud uses it for S3), and k3s is a light Kubernetes. + +**HomeCloud is better** if your code expects AWS APIs beyond S3: IAM, SQS, SNS, Lambda, DynamoDB, RDS, +CloudFormation and the rest are not something MinIO or Kubernetes provide. HomeCloud gives you those +behind one endpoint and one set of credentials. + +**MinIO and k3s are better** if you want Kubernetes-native workloads, need S3 at scale (distributed, erasure +coded MinIO across many disks and nodes), or don't need the rest of the AWS API. Note that MinIO's free +distribution has changed: it no longer publishes free container images, which is why HomeCloud runs +Chainguard's build of the same server (see the [changelog](../CHANGELOG.md), 0.1.1). + +## OpenStack + +OpenStack is a full private cloud: real VMs, software-defined networks, block and object storage, across +many machines. + +**HomeCloud is better** for AWS tooling and for size: OpenStack has its own APIs (Nova, Neutron, Cinder, +Keystone), so Terraform's AWS provider, boto3 and the AWS CLI don't target it, and it takes a team to install +and operate. HomeCloud is one binary on one Docker host, with AWS's managed services (Lambda, SQS, DynamoDB, +RDS, ...) that OpenStack does not offer in AWS form. + +**OpenStack is better** for real infrastructure: multi-node clusters, live migration, hardware-virtualized +VMs with strong isolation, quotas and multi-tenancy at scale. HomeCloud instances are containers today +(VM-backed instances are in progress, [#3](https://github.com/solinode/homecloud/issues/3)), and it runs on a +single node. + +## The AWS free tier + +**AWS is better** at being AWS: every service, every region, exact behavior, and what you test is what you +ship. For final integration or staging tests, nothing replaces it. + +**HomeCloud is better** when you can't or shouldn't use a real account: offline or air-gapped environments, +classrooms where students would each need an account and a payment card, CI that should not hold cloud +credentials or risk a bill, and experiments you want to break and reset freely. The free tier covers limited +usage of some services for a limited time (AWS has changed its terms for new accounts, so check the current +ones); anything beyond that is billed. + +## HomeCloud's limits, in one place + +- **Single node.** One Docker host runs everything; [multi-node clusters](design/multi-node.md) are designed, + not built. +- **One region, one account.** Cross-region features (replication, multi-Region keys' replicas) are refused. +- **Smaller service coverage** than LocalStack Pro, and a subset of operations within each service + ([aws-compat.md](aws-compat.md)). +- **Instances are containers**, sharing the host kernel, until VM-backed instances land. +- **Young project.** The first release was in September 2026. Expect rough edges, and please + [report them](https://github.com/solinode/homecloud/issues/new/choose). +- **Docker socket access** is root-equivalent on the host, so HomeCloud administrators are host administrators.