z0 - zerops.yaml vs import.yaml, Zerops CA

README.md

@@ -33,7 +33,7 @@ If you have any questions, please feel free to join [Zerops Discord Server](http
   •
   <a href="https://docs.zerops.io/discord">Discord Server</a>
   •
-  <a href="http://linkedin.com/company/zerops/">LinkedIn</a>
+  <a href="https://linkedin.com/company/zerops/">LinkedIn</a>
   </b>
 </div>
 

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: <repo-url>` to your service configuration for one-time build during import. See [import documentation](/references/import#service-basic-configuration).
+Add `buildFromGit: <repo-url>` to your service configuration for one-time build during import. See [Import YAML documentation](/references/import#service-basic-configuration).
+
+<YamlConfigsNote />
 
 ## Build phase
 

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.',
       },
     },
   ]}

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

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.
+
+<YamlConfigsNote />
 
 ## 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.
+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).

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 <service-hostname>:6380 -verify_return_error </dev/null
+# look for: Verify return code: 0 (ok)
+```
+
+## When to use it
+
+Use the Zerops CA whenever your client needs to verify a TLS certificate issued by Zerops. The most common cases are:
+
+- Connecting to a [managed PostgreSQL](/postgresql/how-to/connect#method-2-connect-via-direct-ip-access) over the public TLS port (`6432`, via pgBouncer)
+- Connecting to [managed Valkey](/valkey/overview) on its TLS ports (`6380`, or `7001` in HA setups)
+- Any other Zerops-signed TLS endpoint reached from outside the project's private network
+
+The same CA also signs internal TLS endpoints, so it can be useful when verifying certificates from inside a Zerops project too.
+
+:::note
+You do **not** need the CA for HTTPS traffic on `.zerops.app` subdomains or on custom domains &mdash; those use publicly-trusted certificates (Let's Encrypt by default), which every operating system already trusts.
+:::
+
+## Usage examples
+
+### psql (PostgreSQL)
+
+Pass the CA via `sslrootcert` and require certificate verification with `sslmode=verify-full`:
+
+```bash
+psql "host=<public-ip> port=6432 user=<user> dbname=db \
+      sslmode=verify-full sslrootcert=./zerops-ca.pem"
+```
+
+Or as a connection string:
+
+```
+postgresql://<user>:<password>@<public-ip>:6432/db?sslmode=verify-full&sslrootcert=./zerops-ca.pem
+```
+
+### redis-cli (Valkey)
+
+```bash
+redis-cli --tls --cacert ./zerops-ca.pem \
+  -h <public-ip> -p 6380 -a <password>
+```
+
+### openssl s_client (debugging)
+
+To confirm the TLS handshake and inspect the served certificate chain:
+
+```bash
+openssl s_client -connect <public-ip>:6432 \
+  -CAfile ./zerops-ca.pem -servername <public-ip>
+```
+
+### 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 &mdash; for example `PGSSLROOTCERT` for libpq, `tls.RootCAs` in Go, or the `ca` option in Node's `tls` module.
+:::

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
 ```
 
+<YamlConfigsNote />
+
 ### 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 <importYamlPath> [flags]
@@ -154,7 +158,7 @@ zcli project project-import <importYamlPath> [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 <importYamlPath> [flags]

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) &mdash; e.g. `redis-cli --tls --cacert ./zerops-ca.pem -h <ip> -p 6380`.
+:::
+
 ## Learn More
 
 - [Official Valkey Documentation](https://valkey.io/docs) - Comprehensive guide to Valkey features

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).*
+*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).

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',
+        },
       ]
     },
     {

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 (
+    <Admonition type="note" title="Import YAML vs. zerops.yaml — two different files">
+      <p>
+        Zerops uses two YAML files that serve different roles. Don't confuse them.
+      </p>
+
+      <p>
+        <strong>Import YAML</strong> — 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.
+      </p>
+
+      <p>
+        <strong><a href="/zerops-yaml/specification">zerops.yaml</a></strong> — 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.
+      </p>
+    </Admonition>
+  );
+};
+
+export default YamlConfigsNote;