Reference: Explanations about how Diploi works and how its architecture is defined # Diploi Project Architecture > A high level explanation of how Diploi works and how projects are setup. ## Diploi in a Nutshell Diploi’s mission is to make deployment into a process that you do not need to think about. Our goal is for you to just focus on the code that defines your app, without worrying about SSL certificates, setting up CI/CD pipelines and other commonly cursed devops demons. We made it possible with a simple architecture to define a new application. In Diploi, you start by first creating a **Project**. A project is the basic building block of your new application. Inside your **Project**, you define the elements that will power your application. There are two types of elements that are part of your **Project**, * **Components**, which are the elements that will be exposed for users to access them. These can be frontend, backend or fullstack, and inside of a project you can have multiple components running at the same time as a monorepo. * **Add-ons**, which are elements that will be accessible to your components only. These can be databases, cache servers, message queues, etc. ### Project Structure To make the following explanations clearer, let’s assume we just created a Project with Bun for the backend and React+vite for the frontend, Redis for caching and PostgreSQL as our app’s database.  ### Deployment Structure After you create a **Project**, you can create **Deployments** which will belong to the **Project**. A deployment creates a managed kubernetes cluster that will your run your application’s Components and Add-ons.  The deployment’s cluster runs the Diploi core process in charge of communicating with our main server, along with Docker containers for each component and add-on that your project has inside independent pods inside the cluster.  So when you launch deployments, you are creating a new cluster for your project, so you can have different deployments for multiple stages of your application.  *** For an detailed walkthrough about how Diploi manages your Projects and Deployments, check [the technical deep dive](/reference/technical-deep-dive). If anything was unclear or you need help, talk with us on [Discord](https://discord.gg/vvgQxVjC8G) or [contact us](mailto:hello@diploi.com). # Built-In Email > Use Diploi's internal SMTP relay for development-friendly email delivery. Diploi provides a lightweight SMTP relay inside every deployment so your applications can send email without provisioning an external provider. The service is intended for development and low-volume operational notifications.\ The SMTP relay is included with your deployment at no additional cost. ## Connection details Connect using these values: * Host: `core.diploi` * Port: `2525` * Authentication: Not required ### Example configuration ```ts import nodemailer from "nodemailer"; const transporter = nodemailer.createTransport({ host: "core.diploi", port: 2525, }); await transporter.sendMail({ to: "user@example.com", subject: "Verify your email", text: "Click the link in the email to verify your account.", }); ``` ## Component integration The Supabase component automatically points its email authentication workflows at this relay, giving you out-of-the-box email confirmation flows without additional configuration. ## Usage limits Caution The relay enforces strict rate limits to keep the service reliable for all tenants. * Maximum 10 messages per hour * Maximum 30 messages per day * Contact support if you need higher throughput ## Header normalization To protect deliverability, Diploi rewrites certain email headers. These headers are stripped if present: * `from` * `to` * `sender` * `reply-to` * `return-path` * `resent-from` * `resent-to` * `resent-sender` * `bcc` * `cc` * `errors-to` * `x-original-from` * `x-envelope-from` Diploi sets the `from` address to your project’s default domain for every message. ## Best practices * Use the relay for development and staging workloads; production-grade email should use a dedicated provider once you outgrow the limits. * Keep transactional content concise to avoid hitting daily limits. * Reach out to support if you need custom limits or additional deliverability controls. # Deployment Lifecycle > A deployment is a full instance of your application. ## Creating a Deployment To start creating a deployment, you must first [create a project](/deploying/creating-a-deployment/). Once you have a project, you can start creating new deployments. In the next steps, we will walkthrough all the properties that can be set up when creating a deployment. ### General Settings Within the general settings of your new deployment, you can define the name of the deployment and its stage.  #### Deployment Name This will identify the internal name of your deployment within your Diploi project. You can change the name of a deployment at any time. Changes to the project name will not affect your deployment, project, repository or dependencies. #### Deployment Stage In Diploi, you have three stages that you can assign to your deployments: ##### Development Development deployments enable remote development and let your application be served online development. It offers a cloud IDE that can be used for remote development and also allows you to SSH into the environment using VSCode. Development deployments often utilize hot module reloading (HMR) or similar techniques to enable quick code updates without server restarts. When using this stage, your code is cloned directly from GitHub without going through the build process. ##### Staging Staging deployments are used for testing and quality assurance purposes. They run a build version of your application, exactly as your Production deployments do but as an independent deployment that would not affect your Production deployment. ##### Production Production deployments host the build version of your application and it is intended to be the version of your application that your users will have access to. ### Size You must choose the appropriate size for your application. You can update the size of your deployment directly from the Options tab of your deployment. \- **XS** - 2 vCPUs and 2 GB of ram - **0,006 €/hour** \- **S** - 2 vCPUs and 4 GB of ram - **0,014 €/hour** \- **M** - 2 vCPUs and 8 GB of ram - **0,048 €/hour** \- **L** - 4 vCPUs and 16 GB of ram - **0,089 €/hour** \- **XL** - 8 vCPUs and 32 GB of ram - **0,182 €/hour** ### Repository In this section, you will be able to define the branch that your deployment will use. You can change the branch source for your deployment from the **Repository & Git** tab of your deployment.  ### Component and Add-on Settings Depending on your project’s components and add-ons, you might be able to make changes to the configuration, changes in this section will not affect other deployments or your project’s default configuration.  ## Cloning a Deployment To duplicate an existing deployment (including its database and configuration), open the deployment dashboard, go to the **Options** tab, and scroll to the bottom. `https://console.diploi.com//project//deployment//options` There, look for the section “Clone Deployment” and click on the “Clone this deployment” button. This will open the cloning wizard, which follows [the same workflow as when you create a new deployment, explained in the previous section](#creating-a-deployment). ## Managing a Deployment Once you have created a deployment inside a project, you can access your deployment’s settings from the project page.  ### Overview From the overview tab, you can see the status of your deployment, view the logs for each component and add-on running and resources used. The overview tab is divided in three core sections: #### Develop Section Only available on Development deployments In this section, you can get the SSH connection string to your development environment and access to the remote IDE environment.  ##### Remote Development Diploi supports remote development by using the remote development capabilities of eg. Visual Studio Code, but any editor that supports editing using an SSH connection will work. For more details, please see the [Remote Development](/building/remote-development/) guide. ##### Connecting using SSH Once you have created a deployment, look for the “Connect via SSH” command on the “Overview” tab. This command can be copied to your terminal of choice to open an SSH connection to the deployment. *** #### Status tree Where you can see the resources your deployment is using and the status of containers that are part of your deployment, logs, SSH connections for each container and their endpoints of all components and add-ons available on your application.  All public facing URL endpoints that your applications expose have SSL encryption by default. #### Deployment Component and Add-on Status In this section you can visualize the status of each component and add-on that defines your deployment.  ##### Status After a deployment is started you can check its status from the Deployments Overview page. Diploi assigns a color to indicate the overall state of the deployment components  * **Green** - the deployment is working correctly * **Yellow** - there is some issue but the deployment still runs * **Red** - there is some bigger issue that needs to be addressed ##### Logs For each container used by your components and add-ons, you can review the logs by clicking on the “logs” button.  This will show the output from the main running process of your component or add-on, and it operates in the same way in both development and staging/production environments.  ##### Restart This action allows you to restart an individual component or add-on, without affecting the configuration of your deployment and other running components.  ##### Connect You can connect directly to each container part of your deployment via SSH. To get the SSH connection string to each container, click on the **Connect +** button next to each container and this will copy the connection string to your clipboard.  ##### Describe In some situations where you need to view how your components and add-ons are actually being implemented and started by Diploi, you can use the **Describe** feature to review the Kubernetes config of a particular component in your deployment.  This will also show additional information, such as debug messages and pod specs, which could be used for debugging and support requests.  *** #### Deployment resources Here you can view how your application is using the resources available to the deployment.  Here you can visualize the overall resource usage of your deployment. You can adjust the timeframe to show 1 minute, 1 hour or 1 day. ##### Disk resizing Every deployment starts with **5 GB** of persistent storage. You can increase the disk size directly from the Cluster panel by clicking **Resize** with no downtime or restart required. For a full guide, see [Resizing Deployment Storage](/deploying/resize-disk). Note that disk resizing is a one-way operation and cannot be decreased afterwards. *** ### Repository & Git Only available on project deployments that are linked to a repository From this tab, you can choose the branch that your deployment will be using as its source. When you push new changes to your selected branch, a [GitHub Actions workflow](/reference/github-action/) will be run in your repository, which creates an updated build of your application and it then updates the environment of your deployment. In this tab, you can also change the attribution of updates to the environment, which by default is attributed to the GitHub account that created the project.  ### Deployment Options From here you can update the deployment’s name, change the size of your deployment, assign a custom domain to the public endpoints exposed by your deployment, update the environment variables used by each component and add-on in your deployment or delete your deployment. #### Updating the Name You can update the deployment’s name used inside of your project.  #### Machine Size You can change the size of the deployment machine that your deployment uses, by first disabling the deployment and then choosing a different size.  #### Endpoint Settings Diploi will by default create a public endpoint for your application and generate SSL certificates for the public endpoints. You can customize the auto-generated domains or if you prefer, you can assign a custom domain. For a more detailed explanation, check the [custom domain guide](/deploying/custom-domain/).  ##### Using a Custom Domain If you want to use a custom domain all you need to do is: 1. Access your domain’s DNS records in your domain host. 2. Create a new CNAME record, pointing to `edge.diploi.com` 3. Make sure to assign a specific name in the CNAME record, as wildcard domains are not fully supported yet. For example, if you use GoDaddy domains, if you want to use a subdomain like `custom.mydomain.com` your DNS configuration would look like this:  #### Managing Environment Variables You can customize the environment variables that each of your components and add-ons use. Some variables are automatically generated from your add-ons into your components.  ## Deleting a Deployment When you don’t need a deployment anymore, you can delete it by looking for the button **Delete deployment** at the bottom of the Options tab. Be aware that this will permanently delete all data stored (such as code, databases etc.) associated with the instance.  # Deployments Explained > A deployment is a full instance of your application. ## What is a Diploi Deployment? In Diploi, a deployment is a full instance of your application, including databases and other services. It also includes storage and current code changes you are working on. In simple terms, a deployment is a cluster that runs your code. *** ## Deployment Types Deployments in Diploi are divided into two general categories, dynamic development deployments and built deployments. ### Dynamic development deployments In Diploi are deployments used for remote development, these have persistent storage for your code so that code changes will stay even if your deployment restarts or shutdown. ### Build deployments In Diploi can be ***Staging*** or ***Production deployments*** and their cluster instances will run the production build of your application. # The Diploi CLI > A CLI to help you debug your applications via terminal interface. Diploi’s development environments come with a CLI, from which you can access the logs of any component or add-on in your deployment, execute commands inside of a running container, and view the current status of a deployment.  ## How to use You can access the CLI by opening a terminal from any development environment in Diploi. To view if the CLI is installed in your environment, you can try running the command `diploi`, and it should show the following output:  ## CLI commands | Command | Description | Example | Availability | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------- | ------------ | | `diploi` | Shows a brief introduction about what you can do with the CLI and lists the commands available | `diploi` | All users | | `diploi help [command]` | Shows the help article for a command | `diploi help exec` | All users | | `diploi logs [component or add-on]` or `diploi log [component or add-on]` | Streams logs from a running component | `diploi logs next` | All users | | `diploi status` | Shows the current status of the deployment from which the command is being run | `diploi status` | Testers only | | `diploi exec [component or add-on] "command"` | Executes a command inside of a component or add-on | `diploi exec next "echo 'test'"` | Testers only | # diploi.yaml Explained > A deployment is a full instance of your application. The `diploi.yaml` file at the root of a Diploi repository is the **Infrastructure as Code (IaC)** configuration file Diploi uses to build the infrastructure for a deployment.\ Our component-based model allows for easy configuration of stacks without making the config overly verbose. The more detailed config for a component, such as HELM charts and other setup files, are housed in dedicated GitHub repositories maintained by the component owners. ```yaml diploiVersion: v1.0 components: - name: Next.js identifier: next package: https://github.com/diploi/component-nextjs#main env: include: - * - name: Bun identifier: bun folder: /api #Optional package: https://github.com/diploi/component-bun#main env: include: - postgres.* - name: Node.js identifier: node package: https://github.com/diploi/component-nodejs#main env: include: - postgres.POSTGRES_USER:DB_USER addons: - name: PostgreSQL identifier: postgres package: https://github.com/diploi/addon-postgres#main ``` ## `components` and `addons` The list of components and addons to be included in a project. Everything in this list can be edited and your infrastucture will adapt. ### `name` The display name for a component. ### `identifier` An internal identifier for a component. **This has to be unique.** The identifier is used as the internal hostname for a component, and as the folder name where the component files are located. Caution If the `folder` parameter is not defined, Diploi will use the component identifier as the folder name where the files for your component will be stored. ### `folder` Indicates to Diploi where to store the files necessary for a component, and is meant to be used when you import an existing application that already has a functioning app running in a specific folder inside your repository. If a component has a `folder` parameter assigned that already exists, Diploi will not generate any new files, and instead it will try to run the component using the files in the directory you are pointing to. ### `package` The URL for the package repository. Version comes after the hashtag `#` symbol. Version can be a Git tag or branch reference. ### `hosts` `hosts` declares the network endpoints a component exposes. Each entry maps a port inside the container to either a public HTTPS endpoint and/or an internal service name reachable only by other components in the same deployment. ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#main hosts: # Public endpoint — gets an SSL certificate and a configurable domain - identifier: api name: API port: 3000 # Internal-only endpoint — accessible by other components but not the public internet - identifier: metrics name: Metrics endpoint: false port: 3001 ``` #### `hosts[].identifier` A unique slug for this host entry within the component. The identifier becomes part of the internal hostname that other components use to reach this service. You can view the full internal hostname in the Diploi Console. #### `hosts[].name` A human-readable label shown in the Diploi Console for this endpoint. #### `hosts[].port` The port your application listens on inside the container. #### `hosts[].endpoint` Controls whether the host is exposed publicly. Defaults to `true`. * **`true`** — Diploi provisions a public HTTPS endpoint with an automatically managed SSL certificate. You can assign a `diploi.app` subdomain or a [custom domain](/deploying/custom-domain/) from the deployment’s **Options** tab. * **`false`** — The service is only reachable by other components inside the same deployment and is never exposed to the public internet. ### `env` ENV values from other components aren’t available by default, but can be configured here. Importing an ENV variable means making it available for processes inside of a component. #### Import From Other Components Imports let you reuse ENV values from other components, keeping everything in sync and avoiding repetitive manual configuration. Open the **Options** tab for any component to see the values it defines, review the ones it currently imports, and override individual entries whenever you need a custom value. ```yaml env: include: # Imports every ENV value from every component - * # Imports all ENV values from a component with the `postgres` identifier - postgres.* # Imports all ENV values that start with `POSTGRES_` from a component with the `postgres` identifier - postgres.POSTGRES_* # Imports all ENV values from all components where an identifier starts with `post` - post* # Imports the `POSTGRES_USER` ENV value from a component with the `postgres` identifier - postgres.POSTGRES_USER # Imports the `POSTGRES_USER` ENV value from a component with the `postgres` identifier and renames it to `DB_USER` - postgres.POSTGRES_USER:DB_USER # Alternative syntax for renaming - path: postgres.POSTGRES_USER name: DB_USER ``` You can use wildcards when importing values. * `*` * Imports every ENV value from every component * `postgres.*` * Imports all ENV values from a component with the `postgres` identifier * `postgres.POSTGRES_*` * Imports all ENV values that start with `POSTGRES_` from a component with the `postgres` identifier * `post*` * Imports all ENV values from all components where an identifier starts with `post` * `postgres.POSTGRES_USER` * Imports the `POSTGRES_USER` ENV value from a component with the `postgres` identifier You can remap individual ENV values while importing them * `postgres.POSTGRES_USER:DB_USER` * Imports the `POSTGRES_USER` ENV value from a component with the `postgres` identifier and renames it to `DB_USER` #### Static Values Static values let you define build-time variables that are exposed to [GitHub Actions workflows](/reference/github-action/). ```yaml env: include: - value: test name: TEST ``` Diploi forwards static values as Docker build arguments. You can access them inside your component’s `Dockerfile` and `Dockerfile.dev` with the `ARG` instruction and promote them to regular environment variables if needed. ```dockerfile ARG TEST ENV TEST_VALUE=$TEST ``` Static values are scoped to the component where they are declared and remain consistent across deployments. Use the **Options** tab when you need runtime configuration instead. You can also overwrite a static ENV value in the **Options** tab without changing it in the config. ### `containerCommands` Overrides the default startup commands for a component’s container. Each component defines sensible defaults, but you can customize them here when your project structure or tooling differs from the component’s assumptions. The alternative to using `containerCommands` is to edit the startup command directly in the `Dockerfile` (for staging and production) or `Dockerfile.dev` (for development) inside your component’s folder. Use `containerCommands` when you want to change the startup command without modifying the Dockerfiles. ```yaml components: - name: Astro identifier: astro package: https://github.com/diploi/component-astro#main containerCommands: developmentStart: bun run dev -- --host productionStart: bun start ``` #### `containerCommands.developmentStart` The command used to start the container in a **development** deployment. This replaces the component’s default development start command. For example, the Astro component defaults to `npm run dev -- --host` and the FastAPI component defaults to `uv run --with uvicorn uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload --reload-dir src --reload-dir .venv/lib`. You can check the default command from the Dockerfile.dev. #### `containerCommands.productionStart` The command used to start the container in a **staging or production** deployment. This replaces the component’s default production start command. For example, the Astro component defaults to `npm start` and the FastAPI component defaults to `uv run --with uvicorn uvicorn src.main:app --host 0.0.0.0 --port 8000 --proxy-headers`. You can check the default command from the Dockerfile. # GitHub Actions > How Diploi uses GitHub Actions to build and push container images for your components. Diploi automatically generates a GitHub Actions workflow in your repository at `.github/workflows/Build.yaml`. This workflow builds Docker images for each component in your stack and pushes them to the Diploi container registry whenever you push code to any branch. ## How it works The workflow runs in two jobs: 1. **Define Components** — reads your `diploi.yaml` and outputs a build matrix describing each component and environment that needs an image. 2. **Build** — runs in parallel for each matrix entry, building and pushing the Docker image using the [`diploi/action-build`](https://github.com/diploi/action-build) action. ## Default workflow ```yaml name: Build Components on: push: branches: - '*' jobs: define-components: name: Define Components runs-on: ubuntu-latest outputs: components: ${{ steps.diploi-meta.outputs.components }} steps: - name: Checkout code uses: actions/checkout@v3 - id: diploi-meta name: Diploi meta uses: diploi/action-components@v1.8 run-builds: name: Build ${{ matrix.name }} ${{ matrix.stage }} runs-on: ubuntu-24.04-arm needs: define-components strategy: fail-fast: false matrix: include: ${{ fromJSON(needs.define-components.outputs.components) }} steps: - name: Checkout code uses: actions/checkout@v3 - name: Diploi build uses: diploi/action-build@v1.12 with: ${{ matrix }} env: project: ${{ secrets.DIPLOI_REGISTRY_PROJECT }} registry: ${{ secrets.DIPLOI_REGISTRY_HOSTNAME }} username: ${{ secrets.DIPLOI_REGISTRY_USERNAME }} password: ${{ secrets.DIPLOI_REGISTRY_PASSWORD }} ``` ## Dockerfiles The build action selects the Dockerfile to use based on the target environment: * **`Dockerfile.dev`** — used for the **development** environment, if it exists in the component’s folder. * **`Dockerfile`** — used for **staging and production** environments, and as a fallback for development if `Dockerfile.dev` is not present. Both files are expected to be located inside the component’s folder (e.g. `my-api/Dockerfile`). ## Registry secrets The workflow expects four repository secrets to be configured. Diploi sets these automatically when you connect your repository. | Secret | Description | | -------------------------- | ----------------------------------------- | | `DIPLOI_REGISTRY_HOSTNAME` | Hostname of the Diploi container registry | | `DIPLOI_REGISTRY_PROJECT` | Project name within the registry | | `DIPLOI_REGISTRY_USERNAME` | Registry login username | | `DIPLOI_REGISTRY_PASSWORD` | Registry login password | ## Build arguments Static ENV values defined in `diploi.yaml` under a component’s `env` block are forwarded to the Docker build as `ARG` variables. See [Static Values](/reference/diploi-yaml#static-values) for details on how to define them. ## Exposing GitHub secrets to the build If your Dockerfile needs access to sensitive values during the build — such as a private npm registry token or an API key for a build-time fetch — you can pass GitHub repository secrets to the build action using Docker BuildKit’s secret mounting. Add a `secrets` key to the `env` block of the build step in your workflow: ```yaml - name: Diploi build uses: diploi/action-build@v1.12 with: ${{ matrix }} env: project: ${{ secrets.DIPLOI_REGISTRY_PROJECT }} registry: ${{ secrets.DIPLOI_REGISTRY_HOSTNAME }} username: ${{ secrets.DIPLOI_REGISTRY_USERNAME }} password: ${{ secrets.DIPLOI_REGISTRY_PASSWORD }} secrets: | NPM_TOKEN=${{ secrets.NPM_TOKEN }} ``` Then mount the secret in your `Dockerfile` using `--mount=type=secret`: ```dockerfile RUN --mount=type=secret,id=NPM_TOKEN \ NPM_TOKEN=$(cat /run/secrets/NPM_TOKEN) npm install ``` Secrets mounted this way are never stored in the image layers, only available during the `RUN` step that mounts them. # Glossary > Terms used in DevOps and Web Development. This glossary clarifies the common terms you’ll find while reviewing our docs, managing deployments, and operating production services on Diploi. [A](#a) · [B](#b) · [C](#c) · [D](#d) · [E](#e) · [F](#f) · [G](#g) · [H](#h) · [I](#i) · [J](#j) · [K](#k) · [L](#l) · [M](#m) · [N](#n) · [O](#o) · [P](#p) · [Q](#q) · [R](#r) · [S](#s) · [T](#t) · [U](#u) · [V](#v) · [W](#w) · [X](#x) · [Y](#y) · [Z](#z) *** ## A ### Add-on A managed service that can run databases, caches, or message brokers. In Diploi, users can attach add-ons to projects within the private network of the project and exposes credentials to components through the console. *See also:* [Learn more about add-ons](/building/add-ons/), [Component](#component) ### Access Token A short-lived credential that grants programmatic access to APIs or CLIs without sharing a human password. *See also:* [Project](#project), [User Role](#user-role) ### Astro A static-first web framework built for content-driven sites with selective hydration. *See also:* [More about components](/building/components/), [Component](#component) ### Audit Log A chronological record of operational and security events across your systems. *See also:* [Project](#project), [Owner Role](#owner-role) *** ## B ### Backup Policy A set of rules defining how and when data snapshots are retained. *See also:* [Add-on](#add-on), [Failover Plan](#failover-plan) ### Base Image A foundational filesystem layer used to build container images. Diploi creates and maintains base images for components and add-ons to ensure consistent environments. *See also:* [Container Image](#container-image) ### Build Pipeline An automated sequence that compiles, tests, and packages your code. Diploi automatically generates a pipeline, through GitHub Actions when a new project is created. *See also:* [CI/CD](#ci-cd), [GitHub Actions](#github-actions) ### Branch Protection Repository rules that restrict who can push or merge into specific branches. *See also:* [Repository Launch](#repository-launch), [Deployment Stage (Development/Staging/Production)](#deployment-stage-developmentstagingproduction) *** ## C ### Component In Diploi, Components are services that execute code programmatically using a specific framework or runtime. Components are run as pods within an app cluster deployment. *See also:* [More about components](/building/components/), [Stack](#stack), [Pod](#pod), [Cluster](#cluster) ### Container Image An immutable package containing application code, runtime, and dependencies. Diploi builds container images via GitHub Actions and stores them in an image registry. *See also:* [Image Registry](#image-registry), [GitHub Actions](#github-actions) ### CI/CD Continuous integration and delivery practices that automate testing and deployment. Diploi creates a default CI/CD workflows that run on GitHub Actions for all projects hosted. *See also:* [Learn more about the Deployment lifecycle in Diploi](/reference/deployments/deployment-lifecycle/), [Deployment Stage (Development/Staging/Production)](#deployment-stage-developmentstagingproduction) ### CNAME A DNS record that aliases one domain name to another host. In Diploi, custom domains use a CNAME pointing to `edge.diploi.com` for Diploi-managed endpoints. *See also:* [How to add a custom domain](/deploying/custom-domain/), [DNS](#dns) ### Custom Domain A human-friendly address that you configure to serve your application. Diploi provisions certificates and routing once you map a custom domain to the deployment’s endpoint. *See also:* [CNAME](#cname), [SSL/TLS](#ssltls) ### CLI CLI is an acronym that stands for **Command Line Interface**, and it is a text-based interface used to interact with a computer system or a specific program by typing commands. ### Cluster A coordinated set of compute resources managed by Kubernetes. In Diploi, each deployment runs on its own single-node Kubernetes cluster managed by Diploi. *See also:* [Kubernetes](#kubernetes), [Single-node Kubernetes Cluster](#single-node-kubernetes-cluster) *** ## D ### Deployment A released instance of your application that users can access. A deployment contains every component, add-on, and environment for a project stage. In Diploi, the components that are part of a deployment are always accessible online via its endpoints. *See also:* [Learn more about the Deployment lifecycle in Diploi](/reference/deployments/deployment-lifecycle/), [Status Tree](#status-tree), [Endpoints](#endpoint) ### Deployment Stage (Development/Staging/Production) A lifecycle progression that separates code promotion into Development, Staging, and Production environments. *See also:* [Deployment](#deployment), [Repository Launch](#repository-launch) ### Development Container Also known as Dev Container, is a container configured to run a development environment to work with a specific codebase. It can be configured with Docker or config files. In Diploi, Dev Containers are used to allow users to connect to code directly from their browser or connecting to the dev container via SSH with their local IDE. ### diploi.yaml A declarative manifest that defines project components, add-ons, environments, and automation. In Diploi, `diploi.yaml` drives provisioning, stack composition, and env import rules for every deployment. *See also:* [More about diploi.yaml](/reference/diploi-yaml/), [Stack](#stack) ### DNS The system that translates domain names into IP addresses. *See also:* [CNAME](#cname), [Endpoint](#endpoint) ### Drift Detection The process of spotting differences between declared infrastructure and the actual runtime state. *See also:* [Status Tree](#status-tree), [Deployment](#deployment) *** ## E ### Endpoint A network-accessible URL or socket where a service listens for requests. Diploi assigns endpoints per component and deployment, with the option of assigning a custom domain to each component’s endpoint. *See also:* [Deployment Stage (Development/Staging/Production)](#deployment-stage-developmentstagingproduction), [Custom Domain](#custom-domain) ### Environment Variable Import Also known as ENV Variable Import, it is a configuration pattern that pulls environment values from an external source into your application. In Diploi, ENV variables can be shared between components and add-ons by declaring it on the `diploi.yaml` file. *See also:* [More about diploi.yaml](/reference/diploi-yaml/), [Secrets Manager](#secrets-manager) ### Error Budget The acceptable amount of downtime or failures within a service-level objective. *See also:* [Metric](#metric), [Status Tree](#status-tree) *** ## F ### Feature Flag A runtime switch that toggles features on or off without redeploying. *See also:* [Environment Variable Import](#environment-variable-import), [Deployment Stage (Development/Staging/Production)](#deployment-stage-developmentstagingproduction) ### Failover Plan A documented strategy for restoring service after infrastructure failure. *See also:* [Single-node Kubernetes Cluster](#single-node-kubernetes-cluster), [Zero Downtime](#zero-downtime) ### Front-end Component A component dedicated to serving web assets or UI logic. In Diploi, front-end components supported include frameworks like Astro, React and SvelteKit. *See also:* [Component](#component) *** ## G ### GitHub Actions GitHub’s automation platform for running workflows triggered by repository events. *See also:* [CI/CD](#ci-cd), [Repository Launch](#repository-launch), [How Diploi uses GitHub Actions](/reference/github-action/), [More about GitHub Actions](https://docs.github.com/en/actions) ### Git Repository A version-controlled store containing your project’s source history. *See also:* [Project](#project), [GitHub Actions](#github-actions) ### Global Configuration Shared settings applied across multiple components or environments. In Diploi, the global configuration for a project lives in `diploi.yaml`. *See also:* [More about diploi.yaml](/reference/diploi-yaml/), [Stack](#stack) *** ## H ### Helm Chart A templated bundle of Kubernetes manifests used to install applications. In Diploi, Helm charts are used along with `diploi.yaml` files to build and host deployments for a project. *See also:* [Explore Diploi’s technical deep dive](/reference/technical-deep-dive/), [Kubernetes](#kubernetes) ### Health Check A programmatic test that inspects the current state of a service, to determine if it is ready, shutdown or in a error state. *See also:* [Component](#component), [Status Tree](#status-tree) ### High Availability An architecture that tolerates failures without noticeable downtime. *See also:* [Single-node Kubernetes Cluster](#single-node-kubernetes-cluster), [Failover Plan](#failover-plan) *** ## I ### Identifier A unique, stable value used to reference a resource or configuration entry. Identifiers are used in the `diploi.yaml` file, to name components and add-ons. *See also:* [Stack](#stack), [More about diploi.yaml](/reference/diploi-yaml/) ### Image Registry A service that stores and distributes container images. *See also:* [Container Image](#container-image), [CI/CD](#ci-cd) ### Infrastructure Secret Sensitive credentials required to provision or connect infrastructure. *See also:* [Environment Variable Import](#environment-variable-import), [Secrets Manager](#secrets-manager) *** ## J ### Job Runner A worker process designed for asynchronous or scheduled tasks. *See also:* [Component](#component), [Stack](#stack) ### JSON Schema A specification describing the structure and validation rules for JSON documents. *See also:* [diploi.yaml](#diploiyaml), [More about diploi.yaml](/reference/diploi-yaml/) *** ## K ### Kubernetes An orchestration platform for deploying and managing containerized workloads. Diploi provisions dedicated Kubernetes clusters per deployment and manages them. *See also:* [Explore Diploi’s technical deep dive](/reference/technical-deep-dive/), [Helm Chart](#helm-chart) ### Kubeconfig A configuration file that stores cluster access credentials and contexts. *See also:* [Kubernetes](#kubernetes), [User Role](#user-role) ### Key Rotation Regularly replacing secrets or cryptographic keys to reduce compromise risk. *See also:* [Infrastructure Secret](#infrastructure-secret), [Environment Variable Import](#environment-variable-import) *** ## L ### Load Balancer A network component that distributes traffic across service instances. *See also:* [Endpoint](#endpoint), [Kubernetes](#kubernetes) ### Log Stream A continuous feed of application or system logs. in Diploi, you can access the log stream of each component and add-on of a active deployment from the deployment dashboard. *See also:* [Component](#component), [Remote Development](#remote-development) ### Lifecycle Hook A script or automation triggered at a specific phase in the deployment lifecycle. *See also:* [GitHub Actions](#github-actions), [Deployment Stage (Development/Staging/Production)](#deployment-stage-developmentstagingproduction) *** ## M ### Monorepo A repository that stores multiple services or libraries in a single codebase. Diploi scaffolds projects as monorepos so components share tooling while deploying independently as containers. *See also:* [Project](#project), [Component](#component) ### Managed Service An infrastructure capability operated by a provider instead of your team. Diploi-managed services include cluster provisioning, certificates, and deployment lifecycle. *See also:* [Add-on](#add-on), [Single-node Kubernetes Cluster](#single-node-kubernetes-cluster) ### Metric A measurable value that helps observe system performance. Diploi shows the CPU load and memory usage, alongside health status signals for components and add-ons. *See also:* [Status Tree](#status-tree), [Observability Stack](#observability-stack) *** ## N ### Namespace A Kubernetes partition that scopes resources within a cluster. In Diploi, each project deployment lives in its own namespace to isolate workloads. *See also:* [Kubernetes](#kubernetes), [Project](#project) ### Network Policy Rules that control how pods communicate within a cluster. Diploi applies restrictive network policy, so add-ons in a deployment are only exposed to the components that belong to the same deployment. *See also:* [Add-on](#add-on), [Component](#component) ### Node A compute instance that runs Kubernetes pods. *See also:* [Single-node Kubernetes Cluster](#single-node-kubernetes-cluster), [Kubernetes](#kubernetes) *** ## O ### Observability Stack The tooling used to collect logs, metrics, and traces. *See also:* [Metric](#metric), [Add-on](#add-on) ### Owner Role A permission level with full administrative control over a project. *See also:* [Project](#project), [User Role](#user-role) *** ## P ### Package (Component Package URL) A reference to a component’s template package hosted at a URL. *See also:* [More about diploi.yaml](/reference/diploi-yaml/), [Component](#component) ### Parent Domain The apex domain under which subdomains are delegated. *See also:* [Custom Domain](#custom-domain), [DNS](#dns) ### Project The top-level grouping of components, add-ons, and environments for an application. In Diploi, a project governs repositories, deployments, permissions, and billing across all stages. *See also:* [more about Project Lifecycle](/reference/projects/project-lifecycle/), [Stack](#stack) ### Pod The smallest deployable unit in Kubernetes containing one or more containers. Diploi hosts each component and add-on as pods, managed by Helm chart inside the deployment. *See also:* [Kubernetes](#kubernetes), [Helm Chart](#helm-chart) *** ## Q ### Queue Worker A service dedicated to processing asynchronous tasks from a queue. *See also:* [Component](#component), [Job Runner](#job-runner) *** ## R ### Remote Development A way to develop applications and sevices using cloud-hosted environments to code, instead of developing locally. In Diploi, users get a Remote Development environment that uses Dev Containers to enable remote access from Cursor and VS Code, using SSH, or directly from the browser, using Diploi’s cloud IDE. *See also:* [Deployment Stage (Development/Staging/Production)](#deployment-stage-developmentstagingproduction), [Endpoint](#endpoint), [Dev Container](#development-container) ### Repository Launch In Diploi, it is the process of connecting a repository and enabling automated deployments for it. *See also:* [Project](#project), [CI/CD](#ci-cd) ### Resource Quota Limits that cap CPU, memory, or storage usage for workloads. *See also:* [Component](#component), [Single-node Kubernetes Cluster](#single-node-kubernetes-cluster) ### Rollback Restoring a system to a previous known-good state. *See also:* [Container Image](#container-image), [Deployment](#deployment) *** ## S ### Stack A set of components and add-ons that are part of a project. *See also:* [Project](#project), [Component](#component) ### Secrets Manager A system for securely storing and distributing sensitive values. *See also:* [Environment Variable Import](#environment-variable-import), [Infrastructure Secret](#infrastructure-secret) ### Service Account A machine identity used by services to authenticate with APIs. *See also:* [Environment Variable Import](#environment-variable-import), [Identifier](#identifier) ### Single-node Kubernetes Cluster A Kubernetes environment where control plane and workloads run on one node. In Diploi, every deployment operates as a single-node Kubernetes cluster. *See also:* [Cluster](#cluster), [Explore Diploi’s technical deep dive](/reference/technical-deep-dive/) ### SSL/TLS Protocols that encrypt data in transit between clients and servers. In Diploi, all SSL/TLS certificates are issued and renewed automatically for all endpoints exposed by a deployment. *See also:* [Custom Domain](#custom-domain), [Endpoint](#endpoint) ### Status Tree A hierarchical view that summarizes the health of related resources. *See also:* [Deployment](#deployment), [Metric](#metric) *** ## T ### Template Project A preconfigured project layout that accelerates new application setups. *See also:* [Package (Component Package URL)](#package-component-package-url) ### Test Pipeline Automated checks that validate code before deployment. *See also:* [Build Pipeline](#build-pipeline), [CI/CD](#ci-cd) *** ## U ### Upgrade Window A scheduled period reserved for applying updates. *See also:* [Failover Plan](#failover-plan), [Zero Downtime](#zero-downtime) ### User Role A permission level that defines what actions a user can perform. *See also:* [Owner Role](#owner-role), [Project](#project) *** ## V ### Version Pinning Is a way to locking dependencies or images to specific versions using package config files. *See also:* [Package (Component Package URL)](#package-component-package-url), [Base Image](#base-image) ### Volume Within the context of Infrastructure-as-Code, a Volume is a storage unit, that can be persistent or shared, used to provide storage to containers. In Diploi, Volumes are persistent, and are provisioned dynamically based on the storage required by a deployment. *See also:* [Helm Chart](#helm-chart), [Component](#component) *** ## W ### Workspace The collaborative area where teams plan, build, and deploy applications. A workspace groups multiple projects and members under one organizational umbrella. *See also:* [Project](#project), [User Role](#user-role) ### Webhook An HTTP callback triggered by events to notify external systems. In Diploi, you can setup custom Webhooks using any of the backend or fullstack components available, eg. FastAPI, Bun, Node. *See also:* [Repository Launch](#repository-launch), [Deployment](#deployment) *** ## X ### X-Forwarded-For Header A proxy header that preserves the original client IP address. *See also:* [Endpoint](#endpoint), [Load Balancer](#load-balancer) *** ## Y ### YAML Schema Rules that describe the allowed structure of YAML files. *See also:* [JSON Schema](#json-schema), [More about diploi.yaml](/reference/diploi-yaml/) *** ## Z ### Zero Downtime Deployments that avoid noticeable service interruption.. *See also:* [Helm Chart](#helm-chart), [Failover Plan](#failover-plan) # Project Lifecycle > How projects are created, managed and deleted. ## Creating a Project This is the first step to deploy a new application using Diploi. To create a project you must: 1. Select the stack of components and add-ons that your application will be using 2. Choose between creating a new repository to store your application’s code or launching without a repository associated for testing purposes Every project is started from the set of components and add-ons you choose and this defines the structure of your project. ### Components You can think of components as the application layer of your project. In Diploi you can have multiple options available to define your application, which you can mix as you wish. #### Components available  **Supabase** new  **FastAPI** new  **n8n** new  **Flask** new  **Laravel** new  **Deno** new  **Next.js**  **Node.js**  **Bun**  **React + Vite**  **Astro**  **SvelteKit**  **Nue**  **Ghost**  **Hono**  **ASP.NET**  **Lovable**  **Blazor**  **Static Website**  **Django** beta  **Python** beta ### Add-ons Add-ons provide services used by your application. In general, add-ons in Diploi are services that do not require direct development work, which can be services like databases, analytics services, CMS dashboards, etc. #### Add-ons available  **PostgreSQL**  **MongoDB**  **Redis**  **MariaDB**  **MinIO** *** ### Previewing your Project In this section, you can see a preview of your monorepo folder structure at root level.  ### Choosing Between Creating a Project with or without a Repository A **Project with a repository** is the default way to set up a project, Diploi bootstraps a new GitHub repository for you and generates a scaffold for your app based on the Stack you choose. additionally Diploi creates a CI/CD pipeline so changes can be persisted across multiple environments and allows your project to be launch in Staging and Production. A **Project without a repository** used when you want to test a Stack or you want to run a simple scripts and apps online without a repository. Caution Once you choose between using a new repository or launching without a repository, you will not be able to change the repository or add a repository. *** ## Managing a Project After creating a project, you will be able to create new deployments and modify the options of the project.  ### Project Deployments You will be able to create deployments. Each deployment represents a cluster that serves your application online. For a deeper dive on deployments, check the article about [Deployments](/reference/deployments/deployment). ### Project Options In this tab you can view and edit properties of your project. #### General From here you can update the project’s name inside Diploi. When you launch new deployments, the new deployment’s name will start by using the project’s name.  #### Parent Domain By default, Diploi generates a domain for your application. The basic structure of a generated domain uses the following logic: ```plaintext ..diploi.app ```  ## Deleting a Project When you no longer need a Project you can delete it by first deleting all deployments within the project and the going to the “options” tab of your projects and look for the actions sections, to delete the project click on the “delete project” button.  # Projects Explained > A project contains the deployments of your application. ## What is a Diploi Project? A Diploi project contains the deployments of your application. A typical setup could be one deployment for production, one for staging and perhaps one development instance per active developer. A project is defined by components and add-ons. A project also connects to a GitHub repository and contains common settings and environment variables. *** ## Project types ### Project with Repository When you choose to create a new project with a new repository, you will be able to launch a new deployments from different branches of your repository, allowing you to have different environments online at the same time without having to configure servers manually.  By default, when you create a new project, a development deployment will be started, which you can use to start developing your application right away and will be active for 12 hours. This development deployment will use your repository’s default branch main branch as its source. ### Project Without a Repository When starting a project without a repository, you get a development environment that you can use to test new technologies, simple scripts, cron jobs, or just to try out Diploi without the need to create a repository. Caution When you start a project a without a repository, **you cannot add a repository later**. Which is why we do not recommend it for projects meant for production. Caution **Projects without a repository** are **not intended for production**, as your code will only exist on the deployment launched, and changes will not be persisted to other deployments you launch within the project. You can create a project without a repository by clicking on the “**Launch Without a Repository**” option inside the “GitHub Repository” section, when creating a new project.  *** If anything was unclear or you need help, talk with us on [Discord](https://discord.gg/vvgQxVjC8G) or [contact us](mailto:hello@diploi.com). # Technical Deep Dive > How it works. People often ask us if going with Diploi will result in vendor lock-in. The short answer is **no**, let’s walkthrough how Diploi works under the hood. To begin with, when you start a deployment, Diploi will internally launch a private Kubernetes cluster for your deployment. When the cluster starts it will launch all services you have selected as individual containers in the cluster and after that, through Kubernetes you are able to monitor and control the cluster until you close it (eg. by pausing or deleting your deployment). #### Stack, Components and Add-ons But how does Diploi know what services to launch? The answer is your stack. Every deployment you launch, uses your selected stack to describe the services, repositories, hosts, storage, etc. that your cluster must use. The kubernetes setup is handled with standard helm charts. In fact all the specifications for our stack building logic are available on GitHub at . In the future we want you to be able to build and maintain your own components and add-ons, allowing for an endless possibility of services to be mixed and matched. If you would like to help us or want custom features to use Diploi, connect with us on [Discord](https://discord.gg/vvgQxVjC8G) or [by email](mailto:hello@diploi.com). #### Builds, CI/CD and Images With Diploi you don’t need to setup build pipelines, host images of your containers or think about CI/CD, but how does this actually work? The normal way of starting a Diploi project is to let Diploi create the GitHub repository for you. In that process Diploi will also set up [GitHub Actions](/reference/github-action/) that will handle image builds when pushing to that repository. These images are pushed to an image repository hosted by us in order to make images as fast as possible when launching deployments. If you want to make modifications to the application container you have full power to control the image created in your own GitHub repository, so you are not restricted to the images Dockerfiles we provide as starting points. In order to make remote development, deployment statuses, etc. work there are certain things that need to be in place. We will provide more documentation on how these things work as the Diploi service matures. #### So What About That Vendor Lock-in Diploi runs on a standard kubernetes setup, with publicly available helm charts and Dockerfiles for the containers. Using all this together with the code you host yourself on GitHub makes it easy for you to migrate your project to any cloud provider with kubernetes support. If you want assistance migrating out of Diploi, you can connect with us on [Discord](https://discord.gg/vvgQxVjC8G) or [by email](mailto:hello@diploi.com).