diff --git a/README.md b/README.md index db50d6f..e77ea25 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,23 @@

- Floci UI - Floci UI + TheCloud

+

TheCloud

+

Any Cloud. Locally.
- A local-first, cloud-aware runtime console for Floci and compatible local cloud emulators. + A self-hosted cloud console for local AWS, Azure and GCP runtimes.

- Latest Release - CI Status - Docker Pulls - Docker Image Size License: MIT

- Floci UI console + TheCloud's Cloud Explorer showing S3 buckets and the selected bucket's details

-Floci UI is the web console for the Floci ecosystem. The current app is centered on a unified `Cloud Explorer` and a cloud-aware `Console Home`. It renders only real data returned by local runtimes and explicit placeholders for work that is not wired yet. +TheCloud is an AWS-Console-style web console for locally running cloud runtimes. It is centered on a unified `Cloud Explorer` and a cloud-aware `Console Home`, and it renders only real data returned by the runtimes, with explicit placeholders for work that is not wired yet. No fake resources, no demo rows, and no mock operational data are shown in normal mode. @@ -42,9 +39,9 @@ Open [http://localhost:4500](http://localhost:4500). ## Exposing To The Internet -Floci UI requires an administrator username, an Argon2id password hash, and a session secret. Copy `.env.example` to `.env`, generate the hash with `cd packages/api && bun run scripts/hash-password.ts ''`, and generate a session secret with `openssl rand -base64 48`. Do not put plaintext passwords in `.env`. +TheCloud requires an administrator username, an Argon2id password hash, and a session secret. Copy `.env.example` to `.env`, generate the hash with `cd packages/api && bun run scripts/hash-password.ts ''`, and generate a session secret with `openssl rand -base64 48`. Do not put plaintext passwords in `.env`. -Put only Floci UI behind Nginx Proxy Manager, terminating TLS there and forwarding to port `4500`. Keep `FLOCI_UI_SECURE_COOKIES=true` in that deployment. Bind Floci core (`4566`) to the Docker network or localhost only: it must not be publicly reachable, because the authenticated UI proxy is the intended access path. Configure Nginx Proxy Manager to pass `X-Forwarded-Proto` and `X-Forwarded-For`, and place Cloudflare or another edge proxy in front of it for public deployments. Set `FLOCI_UI_TRUSTED_PROXIES` to the proxy's IP or CIDR (comma-separated for several hops, e.g. Cloudflare's published ranges when it sits in front of Nginx Proxy Manager); `X-Forwarded-For` is ignored from any other peer, and without it sign-in throttling treats every visitor as the proxy. +Put only TheCloud's console behind Nginx Proxy Manager, terminating TLS there and forwarding to port `4500`. Keep `FLOCI_UI_SECURE_COOKIES=true` in that deployment. Bind TheCloud's AWS runtime (`4566`) to the Docker network or localhost only: it must not be publicly reachable, because the authenticated UI proxy is the intended access path. Configure Nginx Proxy Manager to pass `X-Forwarded-Proto` and `X-Forwarded-For`, and place Cloudflare or another edge proxy in front of it for public deployments. Set `FLOCI_UI_TRUSTED_PROXIES` to the proxy's IP or CIDR (comma-separated for several hops, e.g. Cloudflare's published ranges when it sits in front of Nginx Proxy Manager); `X-Forwarded-For` is ignored from any other peer, and without it sign-in throttling treats every visitor as the proxy. Set `FLOCI_UI_AUTH_MODE=oidc` to use an OIDC provider such as Authentik. Configure `FLOCI_UI_OIDC_ISSUER`, `FLOCI_UI_OIDC_CLIENT_ID`, `FLOCI_UI_OIDC_CLIENT_SECRET`, and `FLOCI_UI_PUBLIC_BASE_URL`; the callback is `${FLOCI_UI_PUBLIC_BASE_URL}/api/auth/oidc/callback`. OIDC mode also requires an allow-list: `FLOCI_UI_OIDC_ALLOWED_GROUPS` (matched against the `groups` claim, read from UserInfo when the ID token omits it) and/or `FLOCI_UI_OIDC_ALLOWED_EMAILS` (verified emails only). Set `FLOCI_UI_OIDC_ALLOW_ALL_USERS=true` only if every user of the identity provider should have console access. @@ -110,13 +107,9 @@ Services marked `No` render as a disabled sidebar row whose tooltip carries the server-supplied reason. Adding one is a catalog row in `packages/api/src/cloud-spi/serviceCatalog.ts` plus an adapter — no frontend change. -

- Azure console home, showing services grouped by category with per-cloud naming and coming-soon reasons -

- -Azure on the same build: the nav is grouped by category, `k8s Engine` is labelled -`AKS` for this provider, and every unavailable service carries a reason — Serverless -reads `coming soon` because the Floci-AZ runtime answers 501 for Azure Functions, +With Azure selected, the nav is grouped the same way, `k8s Engine` is labelled +`AKS` for that provider, and every unavailable service carries a reason: Serverless +reads `coming soon` because the Azure runtime answers 501 for Azure Functions, even though an adapter is registered. ## Current Capability Snapshot @@ -159,7 +152,7 @@ All three clouds, through the unified shell. Current gaps: - EKS and AKS are read-only. On AKS this is a runtime limit rather than a choice: - the shipped floci-az config runs AKS unmocked with no Docker socket to start k3s + the shipped Azure runtime (`floci-az`) config runs AKS unmocked with no Docker socket to start k3s with, so a created cluster never leaves `provisioningState: Failed`. @@ -169,7 +162,7 @@ Current gaps: Relational and document database workflows across providers: -- AWS RDS: list, inspect, create, update, and delete DB instances (PostgreSQL, MySQL, MariaDB) with provider defaults (class `db.t3.micro`, storage 20 GB, username `root`). Updates use generic `PATCH /api/clouds/:cloud/services/:service/resources/:id` mapping to `ModifyDBInstance` for password rotation, IAM authentication, DB subnet group, VPC security groups, option group, and auto minor version upgrade. Instance class, storage, engine, and version are omitted from edit operations because the current local Floci RDS emulator does not support modifying them. +- AWS RDS: list, inspect, create, update, and delete DB instances (PostgreSQL, MySQL, MariaDB) with provider defaults (class `db.t3.micro`, storage 20 GB, username `root`). Updates use generic `PATCH /api/clouds/:cloud/services/:service/resources/:id` mapping to `ModifyDBInstance` for password rotation, IAM authentication, DB subnet group, VPC security groups, option group, and auto minor version upgrade. Instance class, storage, engine, and version are omitted from edit operations because TheCloud's RDS runtime does not support modifying them yet. - AWS RDS Snapshots: account-scoped Snapshots tab listing DB snapshots and supporting snapshot creation. - Azure Cosmos DB NoSQL: database, container, and document workflows. - AWS DynamoDB: table management, item browsing, and Add record. @@ -196,8 +189,8 @@ Frontend regression tests use mocked `/api/*` responses and need no running emul Current gaps: -- AWS RDS snapshot creation: the Cloud Proxy operation is available, but the current Floci runtime does not implement `CreateDBSnapshot` (returns a typed 501 `operation_not_implemented`). Snapshot listing returns a valid empty list. -- AWS RDS instance stop/start operations are not implemented in the current local Floci runtime. +- AWS RDS snapshot creation: the Cloud Proxy operation is available, but TheCloud's runtime does not implement `CreateDBSnapshot` (returns a typed 501 `operation_not_implemented`). Snapshot listing returns a valid empty list. +- AWS RDS instance stop/start operations are not implemented in TheCloud's runtime yet. @@ -280,7 +273,7 @@ Current gaps: AWS SES email capture through the unified Cloud Explorer. -- Lists emails actually captured by Floci SES. +- Lists emails actually captured by TheCloud's SES. - Filters by subject, sender, and recipient. - Inspects sender, recipients, timestamp, and message type. - Displays HTML in a sandboxed preview, text bodies, and captured raw MIME data. @@ -297,10 +290,10 @@ aws ses send-email \ --endpoint-url http://localhost:4566 \ --from sender@example.test \ --destination 'ToAddresses=recipient@example.test' \ - --message 'Subject={Data="Floci SES test",Charset=utf-8},Body={Text={Data="Plain-text test email.",Charset=utf-8},Html={Data="

Hello from Floci

This should render in the SES preview.

",Charset=utf-8}}' + --message 'Subject={Data="TheCloud SES test",Charset=utf-8},Body={Text={Data="Plain-text test email.",Charset=utf-8},Html={Data="

Hello from TheCloud

This should render in the SES preview.

",Charset=utf-8}}' ``` -The email is captured by the local Floci runtime; it is not delivered externally. Open +The email is captured by TheCloud's runtime, and is delivered externally only when an SMTP relay is configured. Open `/cloud-explorer/aws/email` and refresh the mailbox to inspect its Preview, Text, and Raw views. You can also inspect the captured messages directly with: @@ -328,7 +321,7 @@ AWS and GCP, both through the unified shell. Current gaps: -- Azure Functions is registered but the Floci-AZ runtime answers 501 NotImplemented, +- Azure Functions is registered but the Azure runtime answers 501 NotImplemented, so it reports `coming_soon` with that reason rather than appearing available. - GCP Cloud Functions invoke is not wired yet; the capability is advertised as `coming_soon` instead of being silently missing. @@ -381,7 +374,7 @@ Current gaps: ## Product Direction -Floci UI is evolving toward a metadata-driven, cloud-aware console where one web app can render multiple local runtimes through the same shell. +TheCloud is a metadata-driven, cloud-aware console: one web app renders multiple local runtimes through the same shell. The guiding rules are: @@ -393,7 +386,7 @@ The guiding rules are: ## Architecture -![Floci Unified UI Multi-Cloud Architecture](docs/images/floci-unified-ui-architecture.png) +![TheCloud architecture: the console calls TheCloud's API, which dispatches through one proxy and an adapter registry to AWS, Azure and GCP adapters and their local runtimes](docs/images/thecloud-architecture.svg) Short implementation notes live in [docs/implementation-notes.md](docs/implementation-notes.md). @@ -435,9 +428,9 @@ Browser Default compose stack: -- `floci-ui` on `http://localhost:4500` -- `floci-api` on `http://localhost:4501` -- `floci` on `http://localhost:4566` +- `floci-ui` (the console) on `http://localhost:4500` +- `floci-api` (TheCloud's API) on `http://localhost:4501` +- `floci` (TheCloud's AWS runtime) on `http://localhost:4566` Start AWS-only: @@ -467,7 +460,7 @@ Prerequisites: - Node.js 20+ - pnpm 9+ - Bun -- A running local runtime: Floci core, and optionally Floci-AZ / Floci-GCP +- A running local runtime: TheCloud's AWS runtime, and optionally the Azure and GCP runtimes Install dependencies: @@ -483,29 +476,18 @@ cp .env.example packages/api/.env Important: the API runs from `packages/api` and loads environment variables from `packages/api/.env`. -Start Floci AWS Core with Docker: +Start TheCloud's AWS runtime from its repository: ```bash -docker run -d --name floci \ - -p 4566:4566 \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -e FLOCI_DEFAULT_REGION=us-east-1 \ - -u root \ - floci/floci:latest -``` - -Or from a local clone: - -```bash -git clone https://github.com/floci-io/floci.git ../floci +git clone https://gitea.zacksolutions.dev/Zakaria/FlociClone.git ../floci cd ../floci -./mvnw clean quarkus:dev +docker compose up -d # or ./mvnw clean quarkus:dev with JDK 25 ``` Optional local runtimes: -- Floci-AZ on `http://localhost:4577` -- Floci-GCP on `http://localhost:4588` +- Azure runtime (`floci-az`) on `http://localhost:4577` +- GCP runtime (`floci-gcp`) on `http://localhost:4588` Start the UI stack: @@ -614,18 +596,6 @@ When adding new UI surface: - Keep placeholders explicit instead of inventing fake data. - Update this README when the visible UI surface changes. -## Community Projects - -Floci UI is the first-party console, but it is not the only one. The community builds -consoles for Floci too: - -- [floci-dash](https://github.com/ofsazib/floci-dash) — an AWS-Console-style dashboard - for the Floci AWS runtime built on Cloudscape Design. It ships as a single Docker image - and includes an EC2 web terminal. It targets the AWS runtime only, while Floci UI also - covers Azure and GCP, so pick whichever fits your stack. - -Building something for Floci? Open a PR to add it here. - ## License -[MIT](LICENSE) — part of the [Floci](https://floci.io) ecosystem. +[MIT](LICENSE). TheCloud builds on the open-source [Floci](https://floci.io) project. diff --git a/docs/images/floci-black.svg b/docs/images/floci-black.svg deleted file mode 100644 index 00b231f..0000000 --- a/docs/images/floci-black.svg +++ /dev/null @@ -1,200 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/images/floci-ui-console-azure.png b/docs/images/floci-ui-console-azure.png deleted file mode 100644 index 9bd2d00..0000000 Binary files a/docs/images/floci-ui-console-azure.png and /dev/null differ diff --git a/docs/images/floci-ui-console.png b/docs/images/floci-ui-console.png deleted file mode 100644 index 0810e44..0000000 Binary files a/docs/images/floci-ui-console.png and /dev/null differ diff --git a/docs/images/floci-unified-ui-architecture.png b/docs/images/floci-unified-ui-architecture.png deleted file mode 100644 index 2fd0586..0000000 Binary files a/docs/images/floci-unified-ui-architecture.png and /dev/null differ diff --git a/docs/images/floci-white.svg b/docs/images/floci-white.svg deleted file mode 100644 index 3a62781..0000000 --- a/docs/images/floci-white.svg +++ /dev/null @@ -1,200 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/images/thecloud-architecture.svg b/docs/images/thecloud-architecture.svg new file mode 100644 index 0000000..4db0ba6 --- /dev/null +++ b/docs/images/thecloud-architecture.svg @@ -0,0 +1,72 @@ + + TheCloud architecture + The browser talks only to TheCloud's API, which dispatches each request through one proxy service and an adapter registry to a provider adapter, which calls the local AWS, Azure or GCP runtime with that cloud's real API. + + + + + + + + TheCloud architecture + One console for local AWS, Azure and GCP runtimes, using each cloud's real API + + + + Console (React, port 4500) + Nav and pages rendered from each service's schema; calls only /api/* + + + + + + TheCloud API (Bun and Hono, port 4501) + Sign-in, then the generic /api/clouds/:cloud/services/:service routes + + + CloudProxyService + One dispatcher for every request + + + Adapter registry and service catalog + Registered adapters decide what is shown + + + + Schemas describe fields, columns and capabilities; a capability + is only advertised when its adapter can perform it (checked by tests). + + + + + + + + AWS adapters + AWS SDK v3, one per service + + + Azure adapters + Azure runtime client + + + GCP adapters + GCP runtime client + + + + + + + + TheCloud AWS runtime + port 4566 + + + Azure runtime + port 4577, optional + + + GCP runtime + port 4588, optional + diff --git a/docs/images/thecloud-console.png b/docs/images/thecloud-console.png new file mode 100644 index 0000000..eaef22c Binary files /dev/null and b/docs/images/thecloud-console.png differ diff --git a/docs/images/thecloud-logo.png b/docs/images/thecloud-logo.png new file mode 100644 index 0000000..f6eb4ec Binary files /dev/null and b/docs/images/thecloud-logo.png differ