diff --git a/README.md b/README.md index 84a1f91d4..51c209151 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ If you have any questions, please feel free to join [Zerops Discord Server](http • Discord Server • - LinkedIn + LinkedIn diff --git a/apps/docs/content/features/pipeline.mdx b/apps/docs/content/features/pipeline.mdx index e3bb7c559..dac08a594 100644 --- a/apps/docs/content/features/pipeline.mdx +++ b/apps/docs/content/features/pipeline.mdx @@ -5,6 +5,7 @@ description: Learn how to set up a build & deploy pipeline at Zerops. import GroupCards from '../../src/components/GroupCards'; import Image from '/src/components/Image'; +import YamlConfigsNote from '/src/components/YamlConfigsNote'; export const languages = [ { name: "Node.js", link: "/nodejs/how-to/build-pipeline" }, @@ -133,9 +134,11 @@ In **Pipelines & CI/CD settings** section of your service detail: - **Re-deploy last pipeline** - With optional secret env variable updates - **Trigger new pipeline** - From git repo or with custom configuration -#### Using import YAML +#### Using Import YAML -Add `buildFromGit: ` to your service configuration for one-time build during import. See [import documentation](/references/import#service-basic-configuration). +Add `buildFromGit: ` to your service configuration for one-time build during import. See [Import YAML documentation](/references/import#service-basic-configuration). + + ## Build phase diff --git a/apps/docs/content/homepage.mdx b/apps/docs/content/homepage.mdx index a26347b27..8ea992ebb 100644 --- a/apps/docs/content/homepage.mdx +++ b/apps/docs/content/homepage.mdx @@ -117,16 +117,16 @@ items={storages} /> label: 'zerops.yaml', customProps: { icon: Icons['document-text'], - html: 'Configuration file placed to your repository, telling Zerops how to build and start your app.', + html: 'Configuration file placed to your repository, telling Zerops how to build and run your app.', }, }, { type: 'link', href: '/references/import', - label: 'Import file', + label: 'Import YAML', customProps: { icon: Icons['cloud-arrow-up'], - html: 'YAML format that allows you to creates templates or projects and services', + html: 'Infrastructure-as-Code format that allows you to import or export projects and services.', }, }, ]} diff --git a/apps/docs/content/postgresql/how-to/connect.mdx b/apps/docs/content/postgresql/how-to/connect.mdx index b0f293210..ef49f549e 100644 --- a/apps/docs/content/postgresql/how-to/connect.mdx +++ b/apps/docs/content/postgresql/how-to/connect.mdx @@ -154,6 +154,10 @@ Direct IP Access uses [pgBouncer](https://www.pgbouncer.org/) for connection poo Internally, port `5432` is available without SSL (and port `5433` for reads in HA mode). Externally, connections are secured with TLS through pgBouncer (port `6432`) before being routed to your PostgreSQL service. The read replica port is not available for external connections. +:::tip Trusting the TLS certificate +The TLS certificate served on port `6432` is signed by the Zerops Certificate Authority. To verify it from outside Zerops, download and trust the [Zerops CA](/references/networking/zerops-ca) — e.g. `psql "... sslmode=verify-full sslrootcert=./zerops-ca.pem"`. +::: + #### Enable external access 1. Navigate to your PostgreSQL service in the Zerops GUI and choose the **Public Access through IP Addresses** section diff --git a/apps/docs/content/references/import.mdx b/apps/docs/content/references/import.mdx index bc99e7723..cea9050d0 100644 --- a/apps/docs/content/references/import.mdx +++ b/apps/docs/content/references/import.mdx @@ -4,13 +4,15 @@ description: Learn how to define, import and export projects and services using --- import { Dropdown, DropdownItem } from '/src/components/Dropdown'; -import { Tooltip } from 'docs-ui'; +import YamlConfigsNote from '/src/components/YamlConfigsNote'; -The Zerops YAML configuration provides powerful capabilities for both importing and exporting projects and services. This documentation covers how to define your infrastructure as code and move configurations between environments. +The Import YAML configuration provides powerful capabilities for both importing and exporting projects and services. This documentation covers how to define your infrastructure as code and move configurations between environments. + + ## YAML Configuration Basics -The Zerops YAML configuration can be used to create or replicate services in Zerops. You can import configurations in two ways: +The Import YAML configuration can be used to create or replicate services in Zerops. You can import configurations in two ways: - **Using the GUI**: - **For projects**: In the Zerops dashboard, click on **Import a project** in the Projects section @@ -815,4 +817,44 @@ The exported YAML files are compatible with: - The `zcli project project-import` command - The `zcli project service-import` command (for single service exports) -This allows you to easily move configurations between environments or create new instances of your infrastructure. \ No newline at end of file +This allows you to easily move configurations between environments or create new instances of your infrastructure. + +## Editor support (JSON Schema) + +Zerops publishes an official [JSON Schema ↗](https://json-schema.org/) for the Import YAML: + +``` +https://api.app-prg1.zerops.io/api/rest/public/settings/import-project-yml-json-schema.json +``` + +With the schema attached, your editor gives you: + +- **Autocomplete** for every key and nested field (project, services, autoscaling, nginx, embedded `zeropsYaml`, …) +- **Inline documentation** on hover +- **Validation** — typos, wrong types, and missing required fields are flagged as you type +- **Enum suggestions** for fields like `corePackage`, `mode`, `cpuMode`, service `type`, and more + +### Auto-detection via SchemaStore + +The schema is registered with [SchemaStore ↗](https://www.schemastore.org/), so most YAML-aware editors apply it automatically — no setup required — when the file matches: + +- `zerops-import.yml`, `zerops-import.yaml` +- `zerops-*-import.yml`, `zerops-*-import.yaml` (e.g., `zerops-project-import.yaml`, `zerops-service-import.yaml`) + +This covers VS Code (with the [YAML extension by Red Hat ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)), all JetBrains IDEs, and any editor backed by [`yaml-language-server` ↗](https://github.com/redhat-developer/yaml-language-server) (Neovim, Helix, Sublime LSP, …). + +### Manual attachment + +If your file is named differently, add a modeline at the top: + +```yaml +# yaml-language-server: $schema=https://api.app-prg1.zerops.io/api/rest/public/settings/import-project-yml-json-schema.json +project: + name: project0 +services: + - hostname: app + type: nodejs@22 + # ... +``` + +The same URL works in any editor that lets you map a schema to a file pattern manually (e.g., `yaml.schemas` in VS Code `settings.json`, or JetBrains' **JSON Schema Mappings** panel). diff --git a/apps/docs/content/references/networking/zerops-ca.mdx b/apps/docs/content/references/networking/zerops-ca.mdx new file mode 100644 index 000000000..1f3806d65 --- /dev/null +++ b/apps/docs/content/references/networking/zerops-ca.mdx @@ -0,0 +1,111 @@ +--- +title: Zerops Certificate Authority +description: Trust the Zerops CA to verify TLS connections to managed databases and other Zerops-signed TLS endpoints. +--- + +Zerops issues TLS certificates for its managed services (for example PostgreSQL via pgBouncer, or Valkey TLS ports) from its own internal Certificate Authority. When you connect to one of these endpoints over TLS from outside Zerops — your laptop, CI runner, or another piece of infrastructure — the client needs to trust the Zerops CA in order to verify the certificate and complete the handshake. + +## Download the CA + +The Zerops root CA is published as a single PEM file at: + +``` +https://app.zerops.io/ca +``` + +Fetch it directly: + +```bash +curl -L -o zerops-ca.pem https://app.zerops.io/ca +``` + +The downloaded file is a standard PEM-encoded certificate. You can inspect it with `openssl`: + +```bash +openssl x509 -in zerops-ca.pem -noout -subject -issuer -dates +``` + +## Inside Zerops + +If your application or client runs **inside** a Zerops container, you do not need to download anything — the CA is already available on the local filesystem at: + +``` +/etc/zerops-zembed/ca.crt +``` + +Point your TLS client at that path the same way you would point it at a downloaded copy (`sslrootcert=/etc/zerops-zembed/ca.crt`, `--cacert /etc/zerops-zembed/ca.crt`, etc.). It is the same certificate that `https://app.zerops.io/ca` serves. + +The Zerops CA is also pre-installed into the system trust store of **every Zerops container**, so most TLS libraries will verify Zerops-signed certificates without any explicit `--cacert` / `sslrootcert` configuration. You can confirm this in your own container with any of the following: + +```bash +# 1) Subject hash → matching symlink in the system trust dir (Debian/Ubuntu) +ls -l "/etc/ssl/certs/$(openssl x509 -noout -subject_hash -in /etc/zerops-zembed/ca.crt).0" +# e.g. /etc/ssl/certs/59e8696a.0 -> service-intermediate.pem + +# 2) Verify the CA file against the merged system bundle +openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt /etc/zerops-zembed/ca.crt +# expected: /etc/zerops-zembed/ca.crt: OK + +# 3) End-to-end: handshake against a Zerops-signed endpoint without -CAfile +openssl s_client -connect :6380 -verify_return_error port=6432 user= dbname=db \ + sslmode=verify-full sslrootcert=./zerops-ca.pem" +``` + +Or as a connection string: + +``` +postgresql://:@:6432/db?sslmode=verify-full&sslrootcert=./zerops-ca.pem +``` + +### redis-cli (Valkey) + +```bash +redis-cli --tls --cacert ./zerops-ca.pem \ + -h -p 6380 -a +``` + +### openssl s_client (debugging) + +To confirm the TLS handshake and inspect the served certificate chain: + +```bash +openssl s_client -connect :6432 \ + -CAfile ./zerops-ca.pem -servername +``` + +### System-wide trust + +To trust the Zerops CA system-wide (so clients pick it up automatically without an explicit flag): + +- **Debian/Ubuntu:** copy to `/usr/local/share/ca-certificates/zerops-ca.crt` and run `sudo update-ca-certificates` +- **macOS:** `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain zerops-ca.pem` +- **Alpine:** copy to `/usr/local/share/ca-certificates/zerops-ca.crt` and run `update-ca-certificates` + +:::tip +For application code, most TLS libraries accept a custom CA bundle without modifying system trust — for example `PGSSLROOTCERT` for libpq, `tls.RootCAs` in Go, or the `ca` option in Node's `tls` module. +::: diff --git a/apps/docs/content/references/zcli/commands.mdx b/apps/docs/content/references/zcli/commands.mdx index 00310b84c..0192b933a 100644 --- a/apps/docs/content/references/zcli/commands.mdx +++ b/apps/docs/content/references/zcli/commands.mdx @@ -3,6 +3,8 @@ title: Zerops CLI Commands Reference description: A comprehensive reference for all available commands in the Zerops command line tool (zcli) --- +import YamlConfigsNote from '/src/components/YamlConfigsNote'; + ## Basic Usage ```sh @@ -140,9 +142,11 @@ Lists all projects you have access to. zcli project list ``` + + ### project project-import -Creates a new project with one or more services from a YAML definition. +Creates a new project with one or more services from an [Import YAML](/references/import) definition. ```sh zcli project project-import [flags] @@ -154,7 +158,7 @@ zcli project project-import [flags] ### project service-import -Creates one or more services in an existing project from a YAML definition. +Creates one or more services in an existing project from an [Import YAML](/references/import) definition. ```sh zcli project service-import [flags] diff --git a/apps/docs/content/valkey/overview.mdx b/apps/docs/content/valkey/overview.mdx index 77badf14b..1b1a86162 100644 --- a/apps/docs/content/valkey/overview.mdx +++ b/apps/docs/content/valkey/overview.mdx @@ -54,6 +54,10 @@ Our HA implementation uses a unique approach to ensure high availability while m Be aware that replica data may lag slightly behind the master due to asynchronous replication. ::: +:::tip Trusting the TLS certificate +The certificates served on the TLS ports (`6380` and `7001`) are signed by the Zerops Certificate Authority. To verify them from outside Zerops, download and trust the [Zerops CA](/references/networking/zerops-ca) — e.g. `redis-cli --tls --cacert ./zerops-ca.pem -h -p 6380`. +::: + ## Learn More - [Official Valkey Documentation](https://valkey.io/docs) - Comprehensive guide to Valkey features diff --git a/apps/docs/content/zerops-yaml/specification.mdx b/apps/docs/content/zerops-yaml/specification.mdx index 3d1196e82..93c1909ef 100644 --- a/apps/docs/content/zerops-yaml/specification.mdx +++ b/apps/docs/content/zerops-yaml/specification.mdx @@ -665,4 +665,41 @@ Setup cron jobs. See [examples](/zerops-yaml/cron). For more detailed information on specific configurations, refer to the runtime-specific guides linked at the beginning of this document. ::: -*Need help? Join our [Discord community](https://discord.gg/zeropsio).* \ No newline at end of file +*Need help? Join our [Discord community](https://discord.gg/zeropsio).* + +## Editor support (JSON Schema) + +Zerops publishes an official [JSON Schema ↗](https://json-schema.org/) for `zerops.yaml`: + +``` +https://api.app-prg1.zerops.io/api/rest/public/settings/zerops-yml-json-schema.json +``` + +With the schema attached, your editor gives you: + +- **Autocomplete** for every key and nested field +- **Inline documentation** on hover +- **Validation** — typos, wrong types, and missing required fields are flagged as you type +- **Enum suggestions** for fields like `base` or `cache` + +### Auto-detection via SchemaStore + +The schema is registered with [SchemaStore ↗](https://www.schemastore.org/), so most YAML-aware editors apply it automatically — no setup required — when the file is named: + +- `zerops.yml` +- `zerops.yaml` + +This covers VS Code (with the [YAML extension by Red Hat ↗](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)), all JetBrains IDEs, and any editor backed by [`yaml-language-server` ↗](https://github.com/redhat-developer/yaml-language-server) (Neovim, Helix, Sublime LSP, …). + +### Manual attachment + +If your file is named differently, add a modeline at the top: + +```yaml +# yaml-language-server: $schema=https://api.app-prg1.zerops.io/api/rest/public/settings/zerops-yml-json-schema.json +zerops: + - setup: app + # ... +``` + +The same URL works in any editor that lets you map a schema to a file pattern manually (e.g., `yaml.schemas` in VS Code `settings.json`, or JetBrains' **JSON Schema Mappings** panel). diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js index ef910eb12..1cf814036 100644 --- a/apps/docs/sidebars.js +++ b/apps/docs/sidebars.js @@ -639,6 +639,15 @@ module.exports = { }, className: 'homepage-sidebar-item', }, + { + type: 'doc', + id: 'references/networking/zerops-ca', + label: 'Zerops CA', + customProps: { + sidebar_icon: 'key', + }, + className: 'homepage-sidebar-item', + }, ] }, { diff --git a/apps/docs/src/components/YamlConfigsNote/index.tsx b/apps/docs/src/components/YamlConfigsNote/index.tsx new file mode 100644 index 000000000..8e7d0b6c3 --- /dev/null +++ b/apps/docs/src/components/YamlConfigsNote/index.tsx @@ -0,0 +1,28 @@ +import Admonition from '@theme/Admonition'; +import React from 'react'; + +const YamlConfigsNote: React.FC = () => { + return ( + +

+ Zerops uses two YAML files that serve different roles. Don't confuse them. +

+ +

+ Import YAML — an Infrastructure-as-Code + manifest used to provision infrastructure, configure routing, and seed + secrets. Today it lets you create projects and services via the import + and export mechanisms; routing capabilities are on the roadmap. +

+ +

+ zerops.yaml — the + application deployment description file. It tells Zerops how to build, + deploy, and run a runtime application, and is typically committed to + the application's source-code repository. +

+ + ); +}; + +export default YamlConfigsNote; diff --git a/apps/docs/static/img/mind-maps/lightweight-dark.svg b/apps/docs/static/img/mind-maps/lightweight-dark.svg index a832f59c6..7aa66a452 100644 --- a/apps/docs/static/img/mind-maps/lightweight-dark.svg +++ b/apps/docs/static/img/mind-maps/lightweight-dark.svg @@ -1,84 +1,20 @@ - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + diff --git a/apps/docs/static/img/mind-maps/lightweight.svg b/apps/docs/static/img/mind-maps/lightweight.svg index 067c288f9..b31ad63ee 100644 --- a/apps/docs/static/img/mind-maps/lightweight.svg +++ b/apps/docs/static/img/mind-maps/lightweight.svg @@ -1,95 +1,20 @@ - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + diff --git a/apps/docs/static/img/mind-maps/serious-dark.svg b/apps/docs/static/img/mind-maps/serious-dark.svg index 6fab7c99e..ebeb1f69f 100644 --- a/apps/docs/static/img/mind-maps/serious-dark.svg +++ b/apps/docs/static/img/mind-maps/serious-dark.svg @@ -1,248 +1,59 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/apps/docs/static/img/mind-maps/serious.svg b/apps/docs/static/img/mind-maps/serious.svg index 9acbdf087..890f32c10 100644 --- a/apps/docs/static/img/mind-maps/serious.svg +++ b/apps/docs/static/img/mind-maps/serious.svg @@ -1,266 +1,52 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/bun.lockb b/bun.lockb index c500b5eb5..28abe7f9b 100755 Binary files a/bun.lockb and b/bun.lockb differ