This is the full developer documentation for Diploi Docs # Introduction > Diploi is a platform and workflow to boost development team's efficiency ## What is Diploi? [Diploi explained](https://www.youtube.com/embed/DRhv0SD4E_8?si=LQiltT4DK4PATDiO) Diploi is a platform and workflow for developing and hosting your full application supporting popular frameworks and databases. Use Diploi for * Developing, testing and hosting just about any kind of web application * Quick prototyping of new products * Trying out new technology stacks with close to zero setup time If you started your project on a vibe-coding platform and need better team support, version support and possibility to code using Cursor etc. Diploi could be what you are looking for. ## Key Features * Launch consistent staging, development and production deployments with only a few clicks * Develop without installing or keeping anything locally. * Onboard new team members in only a few clicks * Supports a wide range of projects - from a simple website to a complex service with databases and microservices ### Supported Frameworks and Databases Diploi supports a wide (and growing) range of frameworks and databases, including: #### 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 available  **PostgreSQL**  **MongoDB**  **Redis**  **MariaDB**  **MinIO** #### Starter kits available  **Web App**  **Collaborative Drawing App**  **Chat App**  **OpenClaw Assistant**  **File2AI App** *** ## Prerequisites The only thing you need to use Diploi is a **GitHub account** and a **Web Browser**. Many prefer to use their locally-installed VSCode or Cursor IDE instead of the browser-based IDE. In that case you need to add your SSH key to Diploi in order for remote access to work. ## How it Works Diploi uses a configuration-in-code approach to spin up every deployment as a separate single-node Kubernetes cluster (Don’t worry, you need zero Kubernetes knowledge to use Diploi). Diploi takes care of hostnames, SSL certificates, building and updating Docker images for each service and making it easy to code right on the cluster, aiming for the best possible DX. Diploi works best when you set up your project as a monorepo, where the code for every component lives in a separate folder. If you are interested in more details and reasons for these choices, please see [Technical Deep Dive](/reference/technical-deep-dive/) ## Get started The easiest way to learn Diploi is by launching a new application. For a quick walkthrough [Get Started](/get-started/) here, no registration needed. Note When you create and register you get 50€ in credits so you can get the full Diploi experience at no cost for 14 days. **No credit card required**. After the trial you are charged based on used resources, see [pricing](https://diploi.com/pricing). # Using Add-ons > Add-ons are used to host services and databases for projects. ## 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** Note Services are not exposed publicly by default. They can only be accessed by the components in your project. *** ### PostgreSQL An open-source relational database system known for being reliable, and performant handling complex queries and transactions. [How to add PostgreSQL to a project ](/building/add-ons/postgres) [To the repository ](https://github.com/diploi/addon-postgres) [Official documentation for PostgreSQL ](https://www.postgresql.org/docs/) *** ### Redis An in-memory data structure store used as a database, cache, and message broker, known for its high speed and support for various data structures. [How to add Redis to a project ](/building/add-ons/redis) [To the repository ](https://github.com/diploi/addon-redis) [Official documentation for Redis ](https://redis.io/docs/latest/) *** ### Mongo A NoSQL document database that stores data in JSON-like documents. [How to add Mongo to a project ](/building/add-ons/mongo) [To the repository ](https://github.com/diploi/addon-mongo) [Official documentation for Mongo ](https://www.mongodb.com/docs/manual/) *** ### MariaDB An open-source relational database forked from MySQL, with additional features and performance improvements. [How to add MariaDB to a project ](/building/add-ons/mariadb) [To the repository ](https://github.com/diploi/addon-mariadb) [Official documentation for MariaDB ](https://mariadb.com/docs/) *** ### MinIO An S3-compatible object storage service used to save uploads, backups, and other binary data. [How to add MinIO to a project ](/building/add-ons/minio) [To the repository ](https://github.com/diploi/addon-minio) [Official documentation for MinIO ](https://docs.min.io/enterprise/aistor-object-store/) # MariaDB > Provision MariaDB when your Diploi app needs MySQL compatibility. MariaDB is a relational database that’s compatible with MySQL, and adds performance and tooling improvements. You can use MariaDB when your project requires a db compatible with MySQL or if you are migrating existing MySQL workloads. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add MariaDB to your project. ```yaml addons: - name: MariaDB identifier: mariadb package: https://github.com/diploi/addon-mariadb#v1.0.0-url ``` Note * identifier must match the folder name you use for this add-on in your repo. * Components can import ENV from this add-on using env.include: ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#main env: include: - mariadb.* ``` ## See also * [Using Add-ons](/building/add-ons) * [MariaDB add-on repository](https://github.com/diploi/addon-mariadb) * [MariaDB docs](https://mariadb.com/kb/en/documentation/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # MinIO > Provision MinIO as an S3-compatible Diploi add-on. MinIO is an open-source, S3-compatible, object storage system that you can run in Diploi. Use this add-on when your components need to store uploads, backups, or other binary data without relying on an external cloud bucket. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add MinIO to your project. ```yaml addons: - name: MinIO identifier: minio package: https://github.com/diploi/addon-minio#2025-06-13T11-33-47Z ``` Note * identifier must match the folder name you use for this add-on in your repo. * Components can import ENV from this add-on using env.include. For example, an Astro component can expose the MinIO credentials like this: ```yaml components: - name: Astro identifier: astro package: https://github.com/diploi/component-astro#main env: include: - minio.* ``` ## See also * [Using Add-ons](/building/add-ons) * [MinIO add-on repository](https://github.com/diploi/addon-minio) * [MinIO docs](https://docs.min.io/enterprise/aistor-object-store/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Mongo > Attach a Mongo database to Diploi components. Mongo is a document database that stores flexible JSON-like records with dynamic schemas. Use this add-on when your application benefits from schema-less data modeling or rapid iteration. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add Mongo to your project. ```yaml addons: - name: MongoDB identifier: mongo package: https://github.com/diploi/addon-mongo#v8.2.3-url ``` Note * identifier must match the folder name you use for this add-on in your repo. * Components can import ENV from this add-on using env.include. For example, a Next.js API route can rely on Mongo variables like this: ```yaml components: - name: Next.js identifier: nextjs package: https://github.com/diploi/component-nextjs#main env: include: - mongo.* ``` ## See also * [Using Add-ons](/building/add-ons) * [Mongo add-on repository](https://github.com/diploi/addon-mongo) * [MongoDB docs](https://www.mongodb.com/docs/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # PostgreSQL > Provision PostgreSQL as a Diploi add-on for relational data. PostgreSQL is a popular relational database suited for transactional workloads and complex queries. Use this add-on when your application needs structured data storage with ACID guarantees. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add PostgreSQL to your project. ```yaml addons: - name: PostgreSQL identifier: postgres package: https://github.com/diploi/addon-postgres#v18.3-url ``` Note * identifier must match the folder name you use for this add-on in your repo. * Components can import ENV from this add-on using env.include. For example, a FastAPI component can pull Postgres connection variables like this: ```yaml components: - name: FastAPI identifier: fastapi package: https://github.com/diploi/component-fastapi#main env: include: - postgres.* ``` ## See also * [Using Add-ons](/building/add-ons) * [PostgreSQL add-on repository](https://github.com/diploi/addon-postgres) * [PostgreSQL docs](https://www.postgresql.org/docs/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Redis > Add Redis for caching, queues, and ephemeral data in Diploi. Redis is an in-memory data store ideal for caching, rate limiting, queues, and other latency-sensitive workloads. Choose this add-on when your components need fast key-value access or pub/sub messaging. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add Redis to your project. ```yaml addons: - name: Redis identifier: redis package: https://github.com/diploi/addon-redis#v7.4-url ``` Note * identifier must match the folder name you use for this add-on in your repo. * Components can import ENV from this add-on using env.include. For example, a Node.js worker can grab the Redis host and password like this: ```yaml components: - name: Node.js identifier: nodejs package: https://github.com/diploi/component-nodejs#main env: include: - redis.* ``` ## See also * [Using Add-ons](/building/add-ons) * [Redis add-on repository](https://github.com/diploi/addon-redis) * [Redis docs](https://redis.io/docs/latest/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Connecting via SSH > Diploi utilizes SSH keys for user authentication when establishing SSH connections to deployments. Diploi utilizes SSH keys for user authentication when establishing SSH connections to deployments. This authentication method is commonly employed for remote development connections, such as those established through VS Code. To add an SSH key to your Diploi profile, you must: * Generate an SSH key pair * Copy the public SSH key * Add the copied content of your public SSH in Diploi That’s it 🙂 Let’s go through each step in detail. ## Generate a new SSH Key pair * Linux 1. Open a terminal and run: `ssh-keygen` which generates by default an ed25519 key pair. 2. You will get a message, asking you to assign a name for the key pair. ```bash Generating public/private ed25519 key pair. Enter file in which to save the key (/home//.ssh/id_ed25519): ``` 3. After that, you will be prompted to add a passphrase. ```bash Enter passphrase (empty for no passphrase): Enter the same passphrase again: ``` 4. Now your new key pair is ready, you will see the following message: ```bash Your identification has been saved in Your public key has been saved in someKey.pub The key fingerprint is: SHA256:gBVtt/m4zes+/0SZPkd+1wwo @ The key's randomart image is: +--[ED25519 256]--+ | o.. | | o . | | . . . | | . o o. .| | . S .= o.| | o o= o . B| | . o o .o.E .=*| | =.+o+..o +..=o| | .+B*=.. . ooo+| +----[SHA256]-----+ ``` * Windows 1. Using Git Bash, Terminal or WSL run: `ssh-keygen` which generates by default an ed25519 key pair. 2. You will get a message, asking you to assign a name for the key pair. ```bash Generating public/private ed25519 key pair. Enter file in which to save the key (/home//.ssh/id_ed25519): ``` 3. After that, you will be prompted to add a passphrase. ```bash Enter passphrase (empty for no passphrase): Enter the same passphrase again: ``` 4. Now your new key pair is ready, you will see the following message: ```bash Your identification has been saved in Your public key has been saved in someKey.pub The key fingerprint is: SHA256:gBVtt/m4zes+/0SZPkd+1wwo @ The key's randomart image is: +--[ED25519 256]--+ | o.. | | o . | | . . . | | . o o. .| | . S .= o.| | o o= o . B| | . o o .o.E .=*| | =.+o+..o +..=o| | .+B*=.. . ooo+| +----[SHA256]-----+ ``` * Mac 1. Open Terminal and run: `ssh-keygen` which generates by default an ed25519 key pair. 2. You will get a message, asking you to assign a name for the key pair. ```bash Generating public/private ed25519 key pair. Enter file in which to save the key (/home//.ssh/id_ed25519): ``` 3. After that, you will be prompted to add a passphrase. ```bash Enter passphrase (empty for no passphrase): Enter the same passphrase again: ``` 4. Now your new key pair is ready, you will see the following message: ```bash Your identification has been saved in Your public key has been saved in someKey.pub The key fingerprint is: SHA256:gBVtt/m4zes+/0SZPkd+1wwo @ The key's randomart image is: +--[ED25519 256]--+ | o.. | | o . | | . . . | | . o o. .| | . S .= o.| | o o= o . B| | . o o .o.E .=*| | =.+o+..o +..=o| | .+B*=.. . ooo+| +----[SHA256]-----+ ``` Note Alternatively, you can use an existing SSH key. * [How to check for existing keys?](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys) * [How to create an SSH key? walkthrough by GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) ## Copy the public key generated * Linux 1. ssh-keygen generates two files, one with an extension `.pub` and the other without any extension, eg. `someKey.pub` and `someKey`. The one we need right now is `someKey.pub`, which is your public key. You need to copy the contents of your `.pub` file. You can use the `cat` command: ```bash cat someKey.pub ``` 2. By using `cat` you will print the content of the `someKey.pub` file, it will look like this: ```bash ssh-ed25519 AA786grtyreugigyuwifewy65643354qWrjhBLtBSewyweRTIZw5DqD0zj @ ``` All you need to do is copy the entire output. * Windows 1. ssh-keygen generates two files, one with an extension `.pub` and the other without any extension, eg. `someKey.pub` and `someKey`. The one we need right now is `someKey.pub`, which is your public key. You need to copy the contents of your `.pub` file. You can use the `cat` command: ```bash cat someKey.pub ``` 2. By using `cat` you will print the content of the `someKey.pub` file, it will look like this: ```bash ssh-ed25519 AA786grtyreugigyuwifewy65643354qWrjhBLtBSewyweRTIZw5DqD0zj @ ``` All you need to do is copy the output. * Mac 1. ssh-keygen generates two files, one with an extension `.pub` and the other without any extension, eg. `someKey.pub` and `someKey`. The one we need right now is `someKey.pub`, which is your public key. You need to copy the contents of your `.pub` file. You can use the `cat` command: ```bash cat someKey.pub ``` 2. By using `cat` you will print the content of the `someKey.pub` file, it will look like this: ```bash ssh-ed25519 AA786grtyreugigyuwifewy65643354qWrjhBLtBSewyweRTIZw5DqD0zj @ ``` All you need to do is copy the entire output. Note Having trouble finding your public key? Check this thread from StackOverflow about [how to find the public key](https://stackoverflow.com/questions/3828164/how-do-i-access-my-ssh-public-key/3828169#3828169). ## Add your public key in Diploi Now that you copied the contents of your public key, you need to add it to your Diploi profile: 1. Go to [your profile settings](https://console.diploi.com/settings). 2. Select “Add new SSH key”. 3. Provide a description for your key, such as “Work MacBook,” to help you remember its origin or purpose. 4. Paste your SSH “public key” into the designated field. 5. Click the “Add SSH Key” button.  Caution Never share your SSH private key with anyone! This key grants access to any deployment you have privileges for, allowing others to authenticate as you. That’s it! Now you can access your deployments using SSH. # Using Components > Components are the core building block in Diploi. ## 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 *** ### Astro A static site builder that lets you write components with your a broad selection of frontend frameworks, while optimizing for performance and modern SEO practices. [To the tutorial ](https://diploi.com/blog/hosting_astro_apps) [How to add Astro to a project ](/building/components/astro) [To the component's repository ](https://github.com/diploi/component-astro) [Official documentation for Astro ](https://docs.astro.build/en/getting-started/) *** ### ASP.NET ASP.NET (ASP.NET Core) is an open-source .NET web framework for building web apps and APIs with C#. [How to add ASP.NET to a project ](/building/components/asp) [To the component's repository ](https://github.com/diploi/component-asp) [Official documentation for ASP.NET ](https://learn.microsoft.com/en-us/aspnet/core/) *** ### Blazor The .NET UI framework for building interactive web apps with C# and Razor components, letting you share code across client and server. [How to add Blazor to a project ](/building/components/blazor) [To the component's repository ](https://github.com/diploi/component-blazor) [Official documentation for Blazor ](https://learn.microsoft.com/en-us/aspnet/core/blazor/) *** ### Bun An JavaScript runtime designed to be faster than Node.js, with native bundling, support for TypeScript, and package management support. [To the tutorial ](https://diploi.com/blog/hosting_bun_apps) [How to add Bun to a project ](/building/components/bun) [To the component's repository ](https://github.com/diploi/component-bun) [Official documentation for Bun ](https://bun.sh/docs) *** ### Deno A JavaScript and TypeScript runtime for APIs and backend services. [To the tutorial ](https://diploi.com/blog/hosting_deno_apps) [How to add Deno to a project ](/building/components/deno) [To the component's repository ](https://github.com/diploi/component-deno) [Official documentation for Deno ](https://docs.deno.com/runtime/manual) *** ### Django A high-level Python web fullstack framework that uses Python. [To the tutorial ](https://diploi.com/blog/hosting_django_apps) [How to add Django to a project ](/building/components/django) [To the component's repository ](https://github.com/diploi/component-django) [Official documentation for Django ](https://docs.djangoproject.com/en/5.2/) *** ### FastAPI A Python framework used to create APIs with automatic documentation. [To the tutorial ](https://diploi.com/blog/hosting_fastapi_apps) [How to add FastAPI to a project ](/building/components/fastapi) [To the component's repository ](https://github.com/diploi/component-fastapi) [Official documentation for FastAPI ](https://fastapi.tiangolo.com/) *** ### Flask A minimalist Python framework, design for lightweight APIs, dashboards, services, and fullstack applications. [To the tutorial ](https://diploi.com/blog/hosting_flask_apps) [How to add Flask to a project ](/building/components/flask) [To the component's repository ](https://github.com/diploi/component-flask) [Official documentation for Flask ](https://flask.palletsprojects.com/) *** ### Ghost An open-source content management system designed for publishing and managing blogs, online publications or websites. [To the tutorial ](https://diploi.com/blog/hosting_a_ghost_blog) [How to add Ghost to a project ](/building/components/ghost) [To the component's repository ](https://github.com/diploi/component-ghost) [Official documentation for Ghost ](https://ghost.org/help/manual/) *** ### Hono A small web framework designed to build APIs and backend applications. [To the tutorial ](https://diploi.com/blog/hosting_hono_apps) [How to add Hono to a project ](/building/components/hono) [To the component's repository ](https://github.com/diploi/component-hono) [Official documentation for Hono ](https://hono.dev/docs/) *** ### Laravel A fullstack PHP framework with native support for modern JS-based frontend frameworks. [To the tutorial ](https://diploi.com/blog/hosting_laravel_apps) [How to add Laravel to a project ](/building/components/laravel) [To the component's repository ](https://github.com/diploi/component-laravel) [Official documentation for Laravel ](https://laravel.com/docs) *** ### n8n A workflow automation platform used to run trigger-driven workloads, using a GUI to setup triggers and logic workflow. [To the tutorial ](https://diploi.com/blog/hosting_n8n) [How to add n8n to a project ](/building/components/n8n) [To the component's repository ](https://github.com/diploi/component-n8n) [Official documentation for n8n ](https://docs.n8n.io/) *** ### Next.js A React-based web development framework for server-side and static web rendering. [To the tutorial ](https://diploi.com/blog/hosting_nextjs_apps) [How to add Next.js to a project ](/building/components/nextjs) [To the component's repository ](https://github.com/diploi/component-nextjs) [Official documentation for Next.js ](https://nextjs.org/docs) *** ### Node.js A runtime used to develop backend applications and APIs using JavaScript. [To the tutorial ](https://diploi.com/blog/hosting_node_apps) [How to add Node.js to a project ](/building/components/nodejs) [To the component's repository ](https://github.com/diploi/component-nodejs) [Official documentation for Node.js ](https://nodejs.org/docs/latest/api/) *** ### Nue.js A framework focused on building lightweight fullstack applications using JavaScript, and with native support for Rust or Zig to run workloads. [To the tutorial ](https://diploi.com/blog/hosting_nuejs_apps) [How to add Nue.js to a project ](/building/components/nue) [To the component's repository ](https://github.com/diploi/component-nue) [Official documentation for Nue.js ](https://nuejs.org/docs/) *** ### React + Vite Mixes Vite’s bundling capabilities and React’s frontend development capabilities, in a component that requires no configuration and provides instant hot module reload for frontend applications. [To the tutorial ](https://diploi.com/blog/hosting_react_apps) [How to add React + Vite to a project ](/building/components/react-vite) [To the component's repository ](https://github.com/diploi/component-react-vite) [Official documentation for Vite ](https://vite.dev/guide/) [Official documentation for React ](https://react.dev/reference/react) *** ### Supabase An open-source backend platform that bundles multiple services into one, such as Postgres, storage, auth, real-time listeners, and edge functions. [To the tutorial ](https://diploi.com/blog/hosting_supabase) [How to add Supabase to a project ](/building/components/supabase) [To the component's repository ](https://github.com/diploi/component-supabase) [Official documentation for Supabase ](https://supabase.com/docs) *** ### SvelteKit A framework for building performant web applications with Svelte, offering server-side rendering. [To the tutorial ](https://diploi.com/blog/hosting_svelte_apps) [How to add SvelteKit to a project ](/building/components/sveltekit) [To the component's repository ](https://github.com/diploi/component-sveltekit) [Official documentation for SvelteKit ](https://svelte.dev/docs/kit/introduction) # ASP.NET > Build applications using .NET. ASP.NET is Microsoft’s open-source web framework for building modern, high-performance web apps and APIs with .NET. Choose this component when you’re shipping server-rendered sites, REST backends, or full-stack applications that benefit from the .NET ecosystem and tooling. Diploi handles the build/publish pipeline and runs your ASP.NET app as a service with the runtime and networking it needs. ## Add ASP.NET to an existing project Paste this entry into the `components` list in `diploi.yaml` to add ASP.NET to your project. ```yaml components: - name: ASP.NET identifier: asp package: https://github.com/diploi/component-asp#v10.0 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include, depending on the db your project uses. Example: ```yaml env: include: - mariadb.* - minio.* - mongo.* - postgres.* - redis.* ``` ## See also * [Using Components](/building/components) * [ASP.NET component repository](https://github.com/diploi/component-asp) * [ASP.NET docs](https://learn.microsoft.com/en-us/aspnet/core/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Astro > Ship Astro sites with Diploi-managed builds and hosting. Astro is a modern static site builder focused on shipping minimal JavaScript to the browser. Choose this component when you are delivering content-heavy marketing sites, blogs, or documentation that benefit from fast page loads. Diploi handles the SSR build pipeline and pushes assets where they need to run. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Astro to your project. ```yaml components: - name: Astro identifier: astro package: https://github.com/diploi/component-astro#v6.1.4 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include, depending on the db your project uses. Example: ```yaml env: include: - mariadb.* - minio.* - mongo.* - postgres.* - redis.* ``` ## See also * [Using Components](/building/components) * [Astro component repository](https://github.com/diploi/component-astro) * [Astro docs](https://docs.astro.build/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Blazor > Launching apps powered by Blazor. Blazor is a .NET web UI framework for building interactive web apps using C# and Razor components instead of JavaScript. Choose this component when you’re building dashboards, internal tools, or full-featured web apps where you want to stay in the .NET ecosystem and share code across client and server. Diploi builds your Blazor project and deploys it with the runtime and assets it needs to run. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Blazor to your project. ```yaml components: - name: Blazor identifier: blazor package: https://github.com/diploi/component-blazor#v10.0 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include, depending on the db your project uses. Example: ```yaml env: include: - mariadb.* - minio.* - mongo.* - postgres.* - redis.* ``` ## See also * [Using Components](/building/components) * [Blazor component repository](https://github.com/diploi/component-blazor) * [Blazor docs](https://learn.microsoft.com/en-us/aspnet/core/blazor/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Bun > Deploy Bun apps and tooling with Diploi. Bun is a high-performance JavaScript runtime that includes a bundler, test runner, and package manager. Use this component when you want Bun’s fast startup times and all-in-one tooling for web services or utilities. Diploi handles the deployment so you can take advantage of Bun without custom infrastructure. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Bun to your project. ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - postgres.* - redis.* ``` ## See also * [Using Components](/building/components) * [Bun component repository](https://github.com/diploi/component-bun) * [Bun docs](https://bun.sh/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Deno > Run Deno apps on Diploi with automated builds and deploys. Deno is a secure JavaScript and TypeScript runtime with batteries-included tooling and standards-based APIs. Use this component when you want Diploi to manage cache-friendly builds and keep Deno services updated without self-hosting. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Deno to your project. ```yaml components: - name: Deno identifier: deno package: https://github.com/diploi/component-deno#v2.5.0 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - postgres.* - minio.* ``` ## See also * [Using Components](/building/components) * [Deno component repository](https://github.com/diploi/component-deno) * [Deno docs](https://docs.deno.com/runtime/manual) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Django > Run Django projects on Diploi with managed deploys. Django is a batteries-included Python framework for building secure, database-driven applications. Use this component when you need an admin interface, ORM, and templating system out of the box. Diploi provisions the deployment pipeline so you can focus on models and views instead of infrastructure. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Django to your project. ```yaml components: - name: Django identifier: django package: https://github.com/diploi/component-django#v6.0.3 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - mariadb.* ``` ## See also * [Using Components](/building/components) * [Django component repository](https://github.com/diploi/component-django) * [Django docs](https://docs.djangoproject.com/en/stable/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # FastAPI > Deploy FastAPI services through Diploi’s managed component. FastAPI is a modern, async Python framework that makes it easy to build performant APIs with automatic OpenAPI docs. Use this component when you want Diploi to run uvicorn builds and handle deploys so you can focus on type-safe endpoints and business logic. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add FastAPI to your project. ```yaml components: - name: FastAPI identifier: fastapi package: https://github.com/diploi/component-fastapi#v0.135.2 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - mongo.* ``` ## See also * [Using Components](/building/components) * [FastAPI component repository](https://github.com/diploi/component-fastapi) * [FastAPI docs](https://fastapi.tiangolo.com/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Flask > Deploy lightweight Flask services on Diploi without custom infra. Flask is a minimalist Python framework for APIs, dashboards, and microservices. Use this component when you want Diploi to handle the build steps, gunicorn/uvicorn configuration, and deployments while you focus on routes and extensions. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Flask to your project. ```yaml components: - name: Flask identifier: flask package: https://github.com/diploi/component-flask#v3.1.3-uv ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - redis.* ``` ## See also * [Using Components](/building/components) * [Flask component repository](https://github.com/diploi/component-flask) * [Flask docs](https://flask.palletsprojects.com/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Ghost > Host Ghost to publish blogs and newsletters with Diploi. Ghost is an open-source content platform for publishing blogs, newsletters, and membership sites. Use this component when you want Diploi to manage builds and deployments for a Ghost site. It keeps your content workflow together with the infrastructure that serves it. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Ghost to your project. ```yaml components: - name: Ghost identifier: ghost package: https://github.com/diploi/component-ghost#v5.130.0 env: include: - mariadb.MARIADB_HOST:database__connection__host - mariadb.MARIADB_USER:database__connection__user - mariadb.MARIADB_PASSWORD:database__connection__password ``` Note * identifier must match the folder name you use for this component in your repo. * Your project must have a MariaDB instance, [click here for more info](/building/add-ons/mariadb). * In Diploi, Ghost uses MariaDB for storage, so you need to add a MariaDB to your deployment and use the environment variables as defined here: ```yaml env: include: - mariadb.MARIADB_HOST:database__connection__host - mariadb.MARIADB_USER:database__connection__user - mariadb.MARIADB_PASSWORD:database__connection__password ``` ## See also * [Using Components](/building/components) * [Ghost component repository](https://github.com/diploi/component-ghost) * [Ghost docs](https://ghost.org/docs/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Hono > Deploy lightweight Hono APIs across Diploi’s infrastructure. Hono is a tiny, high-performance web framework tuned for edge and serverless workloads. Choose this component when you need fast APIs or request handlers with minimal overhead. Diploi takes care of packaging and deploying so you can focus on routing and middleware logic. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Hono to your project. ```yaml components: - name: Hono identifier: hono package: https://github.com/diploi/component-hono#v4.7.11 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - postgres.* - redis.* ``` ## See also * [Using Components](/building/components) * [Hono component repository](https://github.com/diploi/component-hono) * [Hono docs](https://hono.dev/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Laravel > Deploy Laravel applications on Diploi with managed builds and releases. Laravel is a modern PHP framework with expressive routing, ORM, queues, and first-class testing utilities. Use this component when you want Diploi to run the build pipeline, publish assets, and keep your Laravel workloads updated without manually scripting servers. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Laravel to your project. ```yaml components: - name: Laravel identifier: laravel package: https://github.com/diploi/component-laravel#v13 # Optional: # env: # include: # - mariadb.* ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - mariadb.* ``` ## See also * [Using Components](/building/components) * [Laravel component repository](https://github.com/diploi/component-laravel) * [Laravel docs](https://laravel.com/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # n8n > Automate workflows with the n8n component managed by Diploi. n8n is a workflow automation platform for connecting APIs, services, and custom logic. Use this component when you need Diploi to build and deploy n8n so you can focus on building workflows, not configuring runtime environments. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add n8n to your project. ```yaml components: - name: n8n identifier: n8n package: https://github.com/diploi/component-n8n#v2.13.4 env: include: - postgres.POSTGRES_HOST:DB_POSTGRESDB_HOST - postgres.POSTGRES_PORT:DB_POSTGRESDB_PORT - postgres.POSTGRES_USER:DB_POSTGRESDB_USER - postgres.POSTGRES_PASSWORD:DB_POSTGRESDB_PASSWORD addons: - name: PostgreSQL identifier: postgres package: https://github.com/diploi/addon-postgres#v18.3-url ``` Note * In Diploi, n8n uses Postgres for database, so you need to add a Postgres db if your deployment doesn’t have one available. [Click here to learn how to add Postgres to your project](/building/add-ons/postgres). * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include: ```yaml env: include: - postgres.POSTGRES_HOST:DB_POSTGRESDB_HOST - postgres.POSTGRES_PORT:DB_POSTGRESDB_PORT - postgres.POSTGRES_USER:DB_POSTGRESDB_USER - postgres.POSTGRES_PASSWORD:DB_POSTGRESDB_PASSWORD ``` Caution In n8n, you must use the environment variable names defined by their documentation. For more information check: ## See also * [Using Components](/building/components) * [n8n component repository](https://github.com/diploi/component-n8n) * [n8n docs](https://docs.n8n.io/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Next.js > Deploy production-ready Next.js apps with server rendering on Diploi. Next.js is a React framework for building server-rendered and statically generated applications. Choose this component when you want Diploi to handle optimized builds, routing, and image processing without extra configuration. It works well for SaaS dashboards, marketing pages, and any React project that needs reliable hosting. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Next.js to your project. ```yaml components: - name: Next.js identifier: next package: https://github.com/diploi/component-nextjs#v16.1.2-ports ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - postgres.* ``` ## See also * [Using Components](/building/components) * [Next.js component repository](https://github.com/diploi/component-nextjs) * [Next.js docs](https://nextjs.org/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Node.js > Run general-purpose Node.js services on Diploi. The Node.js component gives you a standard runtime for JavaScript or TypeScript backends. Reach for it when you need an API, webhook processor, or background worker built with the Node ecosystem. Diploi builds and deploys your code while keeping environment variables and dependencies managed. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Node.js to your project. ```yaml components: - name: Node.js identifier: node package: https://github.com/diploi/component-nodejs#v24.13.0 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - postgres.* ``` ## See also * [Using Components](/building/components) * [Node.js component repository](https://github.com/diploi/component-nodejs) * [Node.js docs](https://nodejs.org/en/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Nue.js > Deploy Nue.js apps with Diploi handling builds and deploys. Nue.js is a minimal framework for composing modular web applications with fast SSR. Pick this component when you want Nue’s lean runtime while keeping deployment automation simple. Diploi runs the build and serves the output so you can focus on your UI modules. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Nue.js to your project. ```yaml components: - name: Nue identifier: nue package: https://github.com/diploi/component-nue#v1.0.0-rc.3 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - mariadb.* ``` ## See also * [Using Components](/building/components) * [Nue.js component repository](https://github.com/diploi/component-nue) * [Nue.js docs](https://nuejs.org/docs/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # React + Vite > Bundle React apps quickly with the React + Vite component. The React + Vite component pairs Vite’s fast bundler with a ready-to-serve React runtime. Use it when you need quick rebuilds, hot module reload, and a lightweight deployment target for frontend projects. Diploi handles the build pipeline so you can focus on UI work. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add React + Vite to your project. ```yaml components: - name: React + Vite identifier: react-vite package: https://github.com/diploi/component-react-vite#v19.2.4-ports ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - mongo.* ``` ## See also * [Using Components](/building/components) * [React + Vite component repository](https://github.com/diploi/component-react-vite) * [React docs](https://react.dev/learn) * [Vite docs](https://vitejs.dev/guide/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Supabase > Deploy Supabase edge functions and services using Diploi components. Supabase bundles Postgres, real-time listeners, storage, and auth with edge functions. Use this component when you want Diploi to manage Supabase deployments alongside the rest of your stack so you can ship a unified backend without wiring infrastructure by hand. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Supabase to your project. ```yaml components: - name: Supabase identifier: supabase package: https://github.com/diploi/component-supabase#v2026.02 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - redis.* ``` ## See also * [Using Components](/building/components) * [Supabase component repository](https://github.com/diploi/component-supabase) * [Supabase docs](https://supabase.com/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # SvelteKit > Deploy full-stack SvelteKit apps through Diploi. SvelteKit combines Svelte’s component model with server-side rendering, routing, and adapters. Use this component when you need a fast Svelte frontend that can fetch data server-side or run API endpoints. Diploi runs the build and deployment steps so your project ships with predictable infrastructure. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add SvelteKit to your project. ```yaml components: - name: SvelteKit identifier: sveltekit package: https://github.com/diploi/component-sveltekit#v2.49.5 ``` Note * identifier must match the folder name you use for this component in your repo. * You can import ENV from add-ons into components using env.include. Example: ```yaml env: include: - postgres.* ``` ## See also * [Using Components](/building/components) * [SvelteKit component repository](https://github.com/diploi/component-sveltekit) * [SvelteKit docs](https://kit.svelte.dev/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Using Remote Development > How to develop remotely with Diploi. At the heart of Diploi lies remote development, allowing you to easily work on any of your projects without the need for software installation or maintenance on your local machine, or dealing with containers. With a single click, you can begin your work without local installation hassle. [Remote development using Cursor and Diploi](https://www.youtube.com/embed/gHeJ-gwCtlg?si=1KroAeD_epe538wF) ## Getting Started Diploi is designed to make remote development as seamless as possible. You can start developing on any of your deployments with just a few clicks. All you need is to create a development deployment in your project, which will provide you with a remote environment. You can access development environments through the browser IDE, or connect to them using your favorite IDE via SSH.  ### Using Diploi’s Browser IDE Diploi offers a built-in browser IDE that allows you to start coding immediately without any setup. This is ideal for quick edits or when you need to make changes on the go. To access the browser IDE, navigate to your deployment’s “Overview” tab, found at: `https://console.diploi.com//project//deployment/` From there, you can click on the “Code in the browser” button, which will open the browser IDE in a new tab. ### Using Your Local IDE To connect to your remote development environment using your own IDE, you need to add your public SSH key, which you can do by following the instructions in our [SSH guide](/building/add-ssh-key/). Diploi officially supports: * [VS Code](https://code.visualstudio.com/) with the [Remote Development extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) * [Cursor](https://www.cursor.com/) #### Connecting you IDE If it is the first time you are connecting to a deployment, you will need to add your IDE to the “Develop” section of your deployment, by clicking on the plus icon next to the “Code in the Browser” button.  Note You can pin your preferred IDE to the top of the list of available IDEs by clicking on the pin icon next to the IDE name. Caution If you are developing on a Windows machine with WSL enabled, please note that a Windows VS Code install uses SSH keys on your **Windows** user by default. #### Configuration Your local VS Code configuration will be used for all remote environments, but certain features (like extensions) need to be configured on a per-deployment basis. ### Other IDEs Caution Diploi currently has built-in persistent configuration for VS Code only. This means that you will have to configure/install your other IDE again after a deployment upgrade. Diploi supports any IDE capable of connecting to a remote machine via SSH. This includes terminal-based IDEs like Vim. #### Terminal Based IDEs Simply open an SSH connection to your deployment, and install your favorite IDE. # Using Starter Kits > Launch pre-built, full-stack applications on Diploi with a single click. Starter Kits include everything you need to start developing immediately. ## Starter Kits Starter Kits are complete, pre-configured templates, which can be used as a scaffold to start new applications or to use directly as they are, which you can launch instantly on Diploi. Each starter kit includes a `diploi.yaml` file, Dockerfiles for development and production, and a ready-to-run codebase.. #### Starter kits available  **Web App**  **Collaborative Drawing App**  **Chat App**  **OpenClaw Assistant**  **File2AI App** Note Starter Kits are different from the Stack Builder. The Stack Builder scaffolds a new project from individual [components](/building/components) and [add-ons](/building/add-ons). Starter Kits provide a complete, working application you can build on. You can extend all Starter Kits available with additional components and add-ons. *** ### OpenClaw A self-hosted personal AI assistant that connects to messaging platforms and supports any LLM provider. Comes with an interactive browser terminal to access the OpenClaw CLI without using SSH. [Launch OpenClaw ](https://diploi.com/starter-kit/openclaw) [How to use the OpenClaw starter kit ](/building/starter-kits/openclaw) [Starter kit repository ](https://github.com/diploi/starter-openclaw) [OpenClaw documentation ](https://docs.openclaw.ai/) *** ### Chat App A Slack-like chat application with authentication and realtime features, built with Next.js and Supabase. [Launch Chat App ](https://diploi.com/starter-kit/chat) [How to use the Chat App starter kit ](/building/starter-kits/chat-app) [Starter kit repository ](https://github.com/diploi/starter-chat) *** ### Drawing App A fun, collaborative pixel art drawing application built with Refine and Supabase. [Launch Drawing App ](https://diploi.com/starter-kit/refine-pixels) [How to use the Drawing App starter kit ](/building/starter-kits/drawing-app) [Starter kit repository ](https://github.com/diploi/starter-refine-pixels) [Refine documentation ](https://refine.dev/docs/) *** ### Web App A modern, production-ready template for building full-stack React applications with Supabase. [Launch Web App ](https://diploi.com/starter-kit/web-app) [How to use the Web App starter kit ](/building/starter-kits/web-app) [Starter kit repository ](https://github.com/diploi/starter-web-app) *** ## See also * [Using Components](/building/components) * [Using Add-ons](/building/add-ons) * [Creating a Project](/deploying/creating-a-project) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Chat App > A Slack-like chat application starter kit built with Next.js and Supabase, featuring authentication and realtime messaging. The Chat App is a Slack-like messaging application built with Next.js and Supabase. Use this starter kit when you want a ready-to-run chat application with built-in authentication, realtime messaging, and a modern full-stack architecture that you can extend and customize. ## Tech stack | Technology | Role | | -------------- | ---------------------------------- | | **Next.js** | Full-stack React framework | | **Supabase** | Backend (database, auth, realtime) | | **TypeScript** | Language | To extend a project kickstarted with the Chat App Starter Kit, you can add any of the components and add-ons supported on Diploi. For more information, [click here to learn about how to use the `diploi.yaml`](/reference/diploi-yaml). Note Supabase has its own PostgreSQL database, authentication, emailing and realtime capabilities. For more information about Diploi’s SMTP email capabilities, [click here](/reference/built-in-email). ## Key features * **Realtime messaging:** Powered by Supabase’s realtime subscriptions * **Email authentication:** Built-in auth flow using Supabase Auth and Diploi’s SMTP email server * **Slack-like interface:** Familiar channel-based chat experience ## Launch [Launch Chat App on Diploi](https://diploi.com/starter-kit/chat) ## See also * [Using Starter Kits](/building/starter-kits) * [Starter kit repository](https://github.com/diploi/starter-chat) * [Next.js component](/building/components/nextjs) * [Supabase component](/building/components/supabase) * [Official Next.js documentation](https://nextjs.org/docs) * [Official Supabase documentation](https://supabase.com/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Drawing App > A collaborative pixel art drawing application starter kit built with Refine and Supabase, featuring realtime multi-user canvas support and authentication. The Drawing App is a fun, collaborative pixel art application built with Refine and Supabase. Use this starter kit when you want a ready-to-run creative application that demonstrates realtime collaboration, authentication, and CRUD operations, or as a foundation for building your own realtime collaborative tool. ## Tech stack | Technology | Role | | -------------- | ---------------------------------- | | **Refine** | React-based CRUD framework | | **Supabase** | Backend (database, auth, realtime) | | **TypeScript** | Language | You can modify this stack by making changes to the `diploi.yaml`. For more information, [click here to learn about how to use the `diploi.yaml`](/reference/diploi-yaml). Note This starter kit is a fork from the [Refine Pixels tutorial](https://refine.dev/blog/refine-pixels-guide/), a well-known seven-part guide for building full-stack apps with Refine and Supabase. The Diploi version is pre-configured and ready to launch. ## Key features * **Collaborative drawing** - Multiple users can draw on the same canvas in realtime * **Email authentication** - Built-in auth flow using Supabase Auth and Diploi’s [SMTP email service](/reference/built-in-email) * **Realtime sync** - Powered by Supabase’s realtime subscriptions * **Canvas management** - Create, browse, and share pixel art canvases ## Launch [Launch Drawing App on Diploi](https://diploi.com/starter-kit/refine-pixels) ## See also * [Using Starter Kits](/building/starter-kits) * [Starter kit repository](https://github.com/diploi/starter-refine-pixels) * [Supabase component](/building/components/supabase) * [Official Refine documentation](https://refine.dev/docs/) * [Official Supabase documentation](https://supabase.com/docs) * [Refine Pixels tutorial](https://refine.dev/blog/refine-pixels-guide/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # OpenClaw > A self-hosted personal AI assistant starter kit that connects to messaging platforms like WhatsApp, Telegram, Slack, and Discord, with support for any LLM provider. OpenClaw is an open-source, self-hosted personal AI assistant that connects to messaging platforms including WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, Microsoft Teams, and more. Use this starter kit when you want Diploi to run an OpenClaw instance without having to manually configure the hosting infrastructure for it. Besides offering the easiest way to host OpenClaw on the cloud, Diploi has features that help you start even faster: * Access to a browser terminal, to run CLI commands without requiring a SSH connection.  * Fully configured gpt-4.1-nano model, provided through the Diploi AI gateway.  ## Tech stack | Technology | Role | | ---------------- | -------------------- | | **Node.js** | Runtime | | **TypeScript** | Language | | **Hono** | Wrapper API server | | **React + Vite** | Control UI frontend | | **OpenClaw** | AI assistant runtime | | **gpt-4.1-nano** | AI model | You can extend your OpenClaw project with any of the components and add-ons supported on Diploi. For more information, [click here to learn about how to use the `diploi.yaml` to extend your project](/reference/diploi-yaml). ## Key features * **Multi-platform messaging** - WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, Microsoft Teams, and more * **Browser terminal** - Run OpenClaw CLI commands directly from the browser without SSH * **Pre-configured AI model** - gpt-4.1-nano ready out of the box via the Diploi AI gateway * **Custom control panel** - Welcome page to monitor status, start/stop the gateway, and reset your instance * **API-driven management** - REST endpoints for programmatic control of the gateway * **Self-hosted & open-source** - Full ownership of your data and infrastructure ## How it works On startup, the wrapper server: 1. Initializes `/app/openclaw.json` via `openclaw onboard` under the hood 2. Applies config defaults (gateway token and model provider, access to Diploi’s browser terminal) 3. Starts OpenClaw with a SSL-protected endpoint 4. Proxies `/dashboard` to the OpenClaw dashboard UI, and all other routes to the Vite frontend When finished, you will have access to a custom welcome page which is unique for Diploi, from where you can: * See the general status of your OpenClaw gateway * Start/Stop the gateway globally * Reset OpenClaw to its startup defaults * Interact with the browser terminal and access the OpenClaw CLI * Access the OpenClaw dashboard  The OpenClaw dashboard hasn’t been modified, so you can expect the exact experience you would get if you configure OpenClaw manually. For more information about how to configure your OpenClaw instance, check their official documentation at ### API endpoints The Hono API wrapper exposes a set of endpoints which can be useful to perform programmatical actions on your OpenClaw instance. This is the full list of endpoints exposed: * `GET /healthz` - Health check * `GET /api/dashboard-token` - Retrieve the dashboard token * `GET /api/gateway/status` - Gateway status * `POST /api/gateway/start` - Start the gateway * `POST /api/gateway/stop` - Stop the gateway * `POST /api/gateway/restart` - Restart the gateway * `POST /api/full-reset` - Full reset * `POST /api/logout` - Logout * `WS /api/terminal-ws` - Browser terminal (PTY websocket) ### Environment variables Common variables used by the wrapper: * `PORT` (default: `3000`) - Server port * `HOSTNAME` (default: `0.0.0.0`) - Server hostname * `VITE_HOST` (default: `127.0.0.1`) - Vite dev server host * `VITE_PORT` (default: `5173`) - Vite dev server port * `OPENCLAW_CONFIG_PATH` (default: `/app/openclaw.json`) - Path to OpenClaw config * `OPENCLAW_STATE_DIR` (default: `/app`) - State directory * `OPENCLAW_WORKSPACE_DIR` (default: `/app/workspace`) - Workspace directory * `OPENCLAW_GATEWAY_TOKEN` - Gateway auth token (generated if missing) * `DIPLOI_AI_GATEWAY_URL` / `DIPLOI_AI_GATEWAY_TOKEN` - Optional model proxy wiring * `DIPLOI_LOGIN_SECRET` - Required to validate login cookie * `DIPLOI_LOGIN_USERNAME` / `DIPLOI_LOGIN_PASSWORD` - Credential login ### Project structure ```plaintext server/ index.ts # wrapper server + proxy processManager.ts # gateway lifecycle manager initOpenclaw.ts # OpenClaw config bootstrap + patching api.ts # API routes terminalWs.ts # PTY websocket bridge web/ src/ # React UI Dockerfile.dev # full dev image including OpenClaw build Dockerfile # production runtime image diploi.yaml # Diploi starter metadata ``` ## Launch [Launch OpenClaw on Diploi](https://diploi.com/starter-kit/openclaw) ## See also * [Using Starter Kits](/building/starter-kits) * [Starter kit repository](https://github.com/diploi/starter-openclaw) * [OpenClaw documentation](https://docs.openclaw.ai/) * [OpenClaw GitHub](https://github.com/openclaw/openclaw) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Web App > A modern, production-ready template for building full-stack React applications using React Router, with SSR, TailwindCSS, and TypeScript. The Web App is a modern, production-ready template for building full-stack React applications. Use this starter kit when you want a clean starting point for a React project with server-side rendering, TailwindCSS styling, TypeScript, and an AI-friendly project structure, without spending time on boilerplate setup. ## Tech stack | Technology | Role | | ---------------- | --------------- | | **React** | UI framework | | **React Router** | Routing and SSR | | **TailwindCSS** | Styling | | **TypeScript** | Language | Note This starter kit does not include a database by default. If your application needs persistent data storage, add PostgreSQL or another database add-on when launching, or add one later by updating your `diploi.yaml` file. For more information, [click here learn more about the `diploi.yaml` and how to use it](/reference/diploi-yaml). ## Key features * **Server-side rendering** - Built-in SSR via React Router for performance and SEO * **TailwindCSS** - Utility-first CSS framework pre-configured and ready to use * **TypeScript** - Full type safety across the application * **AI-friendly** - Project structure designed for easy AI-assisted development * **Production-ready** - Optimized build configuration out of the box ## Launch [Launch Web App on Diploi](https://diploi.com/starter-kit/web-app) ## See also * [Using Starter Kits](/building/starter-kits) * [Starter kit repository](https://github.com/diploi/starter-web-app) * [React + Vite component](/building/components/react-vite) * [Official React documentation](https://react.dev) * [Official React Router documentation](https://reactrouter.com) * [Official TailwindCSS documentation](https://tailwindcss.com/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Cloning a Deployment > How to clone an existing deployment In cases when you need to copy an entire deployment with the exact same configuration and database, such as cases when you need to work on a new feature branch that would involve changes to your database, you can use the clone feature to duplicate a deployment. *** ## Cloning a Deployment To clone a deployment, from the deployment’s dashboard, go to the tab **Options** and scroll to the bottom of the page. `https://console.diploi.com//project//deployment//options`  Look for the **Clone Deployment** section, and there you can click on the **Clone this deployment** button to launch the deployment cloning wizard, which is very similar to the deployment creation workflow. Keep in mind During the process of cloning, you will be unable to make changes to the deployment.  ### Assigning a Deployment Type When cloning a deployment, you can also change its stage. So you could clone a Production deployment and then create a clone deployment intended for Development, using your Production data.  For more information about the types of deployment stages, check [this article, which explains the differences between each type](/reference/deployments/deployment-lifecycle#deployment-stage). Note When you create a new development deployment, it will be active for 12 hours, after which it will be automatically shut down to avoid unnecessary costs. For staging and production deployments, they are not started with a time limit, and will remain active until you shut them down manually. ### Selecting the Deployment Size After assigning the stage for the cloned deployment, you can choose the size that the deployment should have. The available deployment sizes include: \- **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**  ### Configuring Environment Variables Clone deployments inherit their Env values from the source deployment, which you can modify before launching the deployment.  ### Launching a Cloned Deployment Once you have finished configuring the type and size of the deployment, along with modifying any environment variables, you are ready to launch by clicking on “Clone Deployment” which can be found at the bottom of the clone creation wizard.  Note There’s no difference between cloned and non-cloned deployments in terms of how they operate. So you can expect it to behave exactly as any other deployment. # Creating a Deployment > How to create a new deployment for a project After you create a Project, a development deployment is automatically created for you, and you can create additional deployments for staging and production environments, or other development environments as needed. *** ## Launching a New Deployment To launch a new deployment, go to the **Deployments** tab inside of your Project: `https://console.diploi.com//project/` And there, you can click on the **Create Deployment** button to launch the deployment creation wizard. [The easiest way to start Remote Development Environments and code without local install using Diploi](https://www.youtube.com/embed/Xu96kVVzgqY?si=Gceaf_vBGXOhcb_x) ### Deployment Types To start a deployment, you have three different options: * **Development** which allows you to start a server on which you can start a remote development environment using VSCode or our browser IDE, or connect directly to the server via SSH. For more about remote development, check out our [Remote Development guide](/building/remote-development/). * **Staging** to test your application and ensure stability before launching changes in your application to production. * **Production** to launch your application when it is ready to be used by your end users. Note When you create a new development deployment, it will be active for 12 hours, after which it will be automatically shut down to avoid unnecessary costs. For staging and production deployments are not started with a time limit, and will remain active until you shut them down manually. ### Choosing a Deployment Size Once you choose the type of deployment you need, choose the size that the deployment should have. The available deployment sizes include: \- **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**  Once you have configured the type and size of your deployment, you can click on the **Create Deployment** button to start your deployment. ## Connecting via SSH to a Deployment If you need to connect via SSH to your deployment, you can do it by getting the SSH connection string from the “Components” and “Add-ons” sections found at the bottom of the “Overview” tab of your deployment, found at: `https://console.diploi.com//project//deployment/` Note Your development environment and, each component and add-on of your app’s stack are running on independent containers. From there, you can copy the SSH connection string for the component or add-on you want to connect to by clicking on the “Connect +” button next to the component or add-on. For more information on how to connect to your deployment via SSH, check out our [SSH guide](/building/add-ssh-key/).  *** ## Shutting Down a Deployment If you want to stop a deployment from running, all you need to do is click on the “enabled” switch from the **Deployments** tab inside of your Project.  Alternatively, you can also shutdown a deployment by clicking on the “enabled” switch found at the top of your Deployment’s status page.  You can restart your Deployment at any time by clicking on the same switch you used for shutdown. When you click on the switch, a dropdown will appear allowing you to choose the amount of time you want the deployment to be active for.  Note When you shutdown a deployment, it will not generate any costs, you are only charged for the time that your deployment is active. # Creating a Project > How to create a new project In Diploi, the process to host a new application online, starts by creating a new Project, which will let you the stack of the application you want to deploy, and then launching a Deployment which will run the application online. The overall process to launch a new application is as follows:  ## Creating the Stack for a Project In Diploi, a project refers to a combination of **components** and **add-ons** (also called **services**) that form the **stack** that will make up your application. Note After you create a Project, you can change the stack of your project by editing the `diploi.yaml` in your project’s repository. For more information on how to do this, check out the [Diploi YAML documentation](/reference/diploi-yaml/) To create a project for your app click **Create Project** from your dashboard: `https://console.diploi.com//projects` Which will open the **Stack Builder** where you can choose the components and add-ons for your project. ### Selecting Components  ### Selecting Add-ons  Note Your project requires at least one component to be selected Once you have chosen the stack for your project, you will be able to see a preview of your selected stack. ### Stack Preview  In the preview you can edit the identifier for each component and add-on you have selected by clicking on the previewed elements of your stack. This will change the folder name of the components in your monorepo and the internal hostname of your add-ons.  ### Choosing a GitHub Repository The last step before launching your project is to configure how your new application’s code will be stored. You have two options available: * **Launch Without a Repository** where you can launch a project without a repository to store your code. This is ideal for testing, where you can run simple scripts or applications which must be accessible online. Learn more about [Launch Without a Repository](/reference/projects/project#launch-without-a-repository). * **Create Repository** where a new repository will be created for your project. Ideal for launching new application intended for production. By creating a new repository for your project, you automagically enable Diploi’s push-to-deployment pipeline, where changes in your repository’s will update the state of your deployment. Learn more about [Create Repository](/reference/projects/project#project-with-repository).  Now that you have selected your preferred stack and the configuration of your project, you can complete the creation of the project by clicking **Launch Stack**. For both types of projects, when you finish creating a new project, a new development deployment will be started for your project, which you can use to start developing your application right away. # Adding Custom Domains > Diploi offers the flexibility to configure custom domains on two levels. Diploi offers the flexibility to configure custom domains on two levels: at the **project** level and at the **deployment** level. ## Project At the project level, you can configure a custom `diploi.app` subdomain that will serve as the base domain for all autogenerated subdomains on deployments. Any new deployment created will automatically use the project’s domain as their base domain name. For example, if you configure `mycompany.diploi.app` as the custom domain at the project level, all autogenerated subdomains will be created as subdomains of `mycompany.diploi.app` (e.g. `app-production.mycompany.diploi.app`, `app-development.mycompany.diploi.app`, etc.). ## Deployment If you want to use a custom domain, eg. `mycompany.com` you can do it by defining a custom domain for a deployment. This provides more fine-grained control over your domain configuration and enables you to override the autogenerated subdomains created at the project level. ### Configuring a Custom Subdomain e.g. `app.example.com` All you need to do is: 1. Access your domain DNS records. 2. Create a new CNAME record, pointing to `edge.diploi.me` and using for name, the subdomain you want to use. 3. Add your custom domain in your Project or Deployment.  Note Depending on your domain hosting service, the configuration above might use different terminology. If anything was unclear or you need help, talk with us on [Discord](https://discord.gg/vvgQxVjC8G) or [contact us](mailto:hello@diploi.com). ### Configuring a Custom Root Domain e.g. `example.com` Root domains (also called apex or base domains) do not officially support CNAME records, which Diploi needs. Many DNS providers offer similar functionality with custom record types like ALIAS or ANAME.\ To point an apex domain to Diploi, you should refer to your DNS providers own instructions.\ We have created a table which lists the recommended records to use with some of the most popular DNS providers: | Provider | Record | Value | | ------------- | ------ | ---------------- | | Cloudflare | CNAME | `edge.diploi.me` | | DNS Made Easy | ANAME | `edge.diploi.me` | | DNSimple | ALIAS | `edge.diploi.me` | | DreamHost | ALIAS | `edge.diploi.me` | | easyDNS | ANAME | `edge.diploi.me` | | Namecheap | ALIAS | `edge.diploi.me` | | PointDNS | ALIAS | `edge.diploi.me` | | Porkbun | ALIAS | `edge.diploi.me` | Note Depending on the DNS provider, an empty or `@` value usually identifies the root domain. So instead of adding a record for `example.com`, it might need to be added to `@` e.g. Note If your DNS provider only supports A records for root domains, please react out to us. We can offer assistance with configuration. # Hosting existing apps > Import your existing applications from GitHub and host them on Diploi If you already have an application that you would like to bring into Diploi, you can import it using **GitHub**. *** ## How to Import an Existing App into Diploi Diploi offers two ways to import projects, by selecting the repo you want to import from a list of available repositories in your GitHub account or by using the URL of a GitHub repo, either a public one or your own. 1. Start a new project  2. Then switch from “Start From Scratch” to the “Import Repository” tab  3. Now you can select the source code you want to import. You can either select a repository stored in your own GitHub account or use a URL to import a public repo. Note You can also import your own repositories via URL, as long as you have approved Diploi to have access to them or if they are public.  4. Once you have selected the repository you’ll import, click on the “Analyze Repository” button. Diploi will then look for the configuration files (`package.json`, ‘requirements.txt’, etc) and readme in your repository, to determine how to properly import your project to Diploi.  The import system will run an automated analysis, and conclude if your project can be hosted on Diploi or not.  Note In cases when Diploi can’t automatically host your imported app, the import result will notify you the reasons why it can’t be configured.  If you need support to import projects, contact us [via email](mailto:hello@diploi.com) or in [Discord](https://discord.com/invite/vvgQxVjC8G). Tip As mentioned before, any repository created using Diploi can be imported without additional configuration required.  5. After Diploi analyzes your repository, you’ll get a report which also tells you if you will need to do additional config work to properly host your application.  The import system will generate a custom `diploi.yaml` file for your app, and you can also expand it by adding additional components and add-ons, like additional databases or services. For more about how to use the `diploi.yaml` file, [click here](/reference/diploi-yaml).  6. Now you should have a development deployment running. If your project is not loading properly or fails to start, check the deployment logs. Tip Diploi uses default port configurations for all supported frameworks and databases, so if your application uses other ports, try first changing your ports to match the ones used by Diploi. You can find the default port config by opening the `Dockerfile.dev` from the remote development environment. ### Other considerations #### Run command config By default, Diploi will use common run commands for development and staging/production deployments, so there might be some situations when your imported application might fail because your project uses different run commands. To handle these situations, you can either modify the `Dockerfile` and `Dockerfile.dev` created by diploi, or modify your app’s config to include the commands used by Diploi to run your application. #### Importing an external public repository When you can import a publicly available repository, which doesn’t belong to your GitHub account, you will have the option of creating a new repository in your account to store your code or start a project without a repository. In case you choose to proceed without a repo, your project won’t be able to start a Production or Staging deployment, because Diploi creates a [GitHub Actions workflow](/reference/github-action/) which takes care of creating a build of your project, which can be ran in Staging and Production. Caution You cannot add a repository to an existing project. If you need to import an application and link it to a new repository, you will need to go through the process of importing the app again and then create a new repository before launching the project. For more information about the differences between projects with or without a repository, [check this article going over their properties](/reference/projects/project#project-types). #### Importing an app from a repository you own When you import from a repo you own, Diploi will use the same repository by default to store your code, so any changes you make to your project can be pushed to the same repository you imported from. Currently, you can’t import a repository and save it in a new repository. Note Once you import an application, you will need to push the files that Diploi creates in your project directly to the `main` branch of your repository. This is needed because Diploi uses Docker in the background to host your application, and it uses a [GitHub Actions workflow](/reference/github-action/) to generate a Docker build that can be used by Diploi. ## Supported Applications Although it is technically possible to import any application, not every app will work right away, and they might require additional work in order to run properly after you import them to Diploi. You can **import any application built with Diploi**, or with any of these frameworks, databases, and technologies: #### 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 available  **PostgreSQL**  **MongoDB**  **Redis**  **MariaDB**  **MinIO** Note You can modify your application’s tech stack [from the `diploi.yaml` file](/reference/diploi-yaml). ### Apps built on Diploi Any application built on Diploi can be imported into a new project without any additional configuration. Diploi will provision any component and add-on specified in the `diploi.yaml` file, but with the caveat that any environment variables used in the project must then be set manually, since Diploi doesn’t store the project’s secrets on GitHub.  Note Any changes to component and/or add-on identifiers and root folders can break the base configuration of a project imported, so remember to update any references that have changed. ### Apps built on Lovable If you built a project on Lovable, you can seamlessly import it to Diploi. All you need to do is sync your application on GitHub. For Lovable projects using Supabase, you can use the open-source version of Supabase that is available on Diploi. You can add Supabase by adding the snippet to your `diploi.yaml` file. ```plaintext - name: Supabase identifier: supabase package: https://github.com/diploi/component-supabase#main ``` Paste the snippet within the `components` field in the `diploi.yaml`, usually found in the root of your project. ```plaintext components: - name: Lovable ... - name: Supabase identifier: supabase package: https://github.com/diploi/component-supabase#main ``` If you would like a detailed walkthrough about how to import an application built with Lovable, [click here to check our tutorial explaining how to do it](https://diploi.com/blog/importing_from_lovable_and_github). We also have a guide walkthrough explaining how to use Cursor for your imported Lovable app, which [you can check by clicking here](https://diploi.com/blog/exporting_from_lovable_to_cursor). Tip To add additional frameworks and databases to your imported Lovable app, add the components and add-ons you would like by modifying the `diploi.yaml` file. [Click here for more information about how to do it](/reference/diploi-yaml). #### Running Supabase Migrations after Importing a Lovable App If you are using the Lovable project with Supabase, you’ll need to run the necessary migrations, which should be stored inside your Supabase folder, as `migrations`. You can apply the migrations to your new Supabase instance by running the command `supabase migration up` from the development environment created when you import the project. Tip Besides `npm`, Diploi also supports `yarn` and `pnpm` as package managers. For Python-based applications, currently we support `uv`, but you can also import apps that use venv and pip. # Resizing Disk Storage > How to increase the disk storage of a deployment using the Storage Selector Every deployment in Diploi includes persistent disk storage used by your components, add-ons, and data. By default, new deployments start with **5 GB** of storage. As your application grows and your data needs increase, you can expand the disk size directly from the deployment dashboard. Important Disk resizing is a **one-way operation**. You can increase the storage size of your deployment, but you cannot decrease it afterward. Plan your storage needs carefully before resizing, as this change is permanent. *** ## Viewing Disk Usage From the **Overview** tab of your deployment, the **Cluster** panel displays real-time resource usage for your deployment, including RAM, CPU, and Disk. The **Disk** section shows how much storage your deployment is currently using, broken down by category: Code, Home, PostgreSQL, Devpod, etc. This gives you a quick overview of where your storage is being consumed.  *** ## Resizing the Disk To increase your deployment’s storage, click the **Resize** button located next to the Disk usage indicator in the Cluster panel. This will open the **Resize Disk** dialog, where you can use the slider to increase your deployment’s storage in 5 GB increments.  Resizing storage will affect your monthly costs. You can review the pricing before confirming by visiting our [pricing page](https://diploi.com/pricing) and checking how much you would pay for the new storage you plan to allocate.  Once you have selected the desired size, click the **Resize** button to confirm. The additional storage will be made available to your deployment. Note Resizing does not require your deployment to be paused or restarted. Your application will continue running during the resize operation. *** ## See also * [Creating a Deployment](/deploying/creating-a-deployment) * [Deployment Lifecycle](/reference/deployments/deployment-lifecycle) # FAQ > Frequently asked questions about Diploi ## Getting Started **Can I use Diploi for production applications?** Yes! Diploi supports production deployments with proper resource allocation, custom domains, and SSL certificates. We provide enterprise-grade infrastructure suitable for production workloads. However, our single-node kubernetes version does not scale infinitely so to support very busy sites Diploi might not yet be the perfect solution. We are hard at work on a more scalable version. See the [roadmap](/roadmap/) for more details. **How much does Diploi cost?** Check our [pricing page](https://diploi.com/pricing) for current pricing information. We offer different tiers to suit various needs, including 100% free trial of the full Diploi experience. Generally speaking Diploi is very affordable when used for development (4€/deployment/month and upward), since you only run the clusters while you are working. A typical production cluster starts from around 20€/month, when you consider that the same cluster can run both your frontend, backend and database we think it can be considered very affordable. **Do I need a GitHub account?** Yes, Diploi requires GitHub integration because it creates repositories for your projects and handles CI/CD builds through GitHub actions. This ensures version control and seamless collaboration. **Can I try Diploi without registering?** Yes! You can use launch a trial without registration. Visit [diploi.com/#StackBuilder](https://diploi.com/#StackBuilder) to start a deployment in seconds. Deployments launched without registration expire after 12 hours but you can claim the account and continue working. ## Features & Capabilities **What frameworks and databases are supported?** See our [components documentation](/building/components/) for a complete list of supported frameworks and databases. We support popular technologies like React, Next.js, Node.js, Python, PostgreSQL, MongoDB, and many more. **Can I migrate an existing project to Diploi?** While Diploi is optimized for new projects, you can import existing projects into diploi. Currently we have decent support for Node and Lovable projects, but we are hard at work at improving this. **Can I use custom domains?** Yes, Diploi supports custom domains with automatic SSL certificate management. See our [custom domain guide](/deploying/custom-domain/) for setup instructions. **How do I update my application?** For projects with repositories, simply push changes to your connected branch. Diploi will automatically rebuild and redeploy your application to the deployments following that branch. It will also consider changes in infrastructure by looking at `Diploi.yaml` Please note that development deployments will only update in part, because you maintain the code part through the editor. **Can I have multiple environments?** Yes! You can create development, staging, and production deployments for the same project, each with different configurations and resource allocations. **What happens if I exceed my limits?** You’ll be notified before reaching limits. Some features may be temporarily restricted until you upgrade or reduce usage. Check your dashboard for current usage statistics. ## Pricing & Plans **Is there a free tier?** Yes, we offer free development deployments with basic resources. These are perfect for testing and learning. **How does billing work?** Billing is based on resource usage and deployment duration. You only pay for what you use, with transparent pricing. **Can I cancel anytime?** Yes, you can cancel your subscription at any time. Your deployments will stop running if you cancel your subscription. ## Security & Data **Is my data secure?** Diploi follows industry best practices for security, including: * Encrypted data transmission (HTTPS/TLS) * Secure infrastructure with regular security updates * Isolated deployments Currently you are required to take care of backups of your data yourself. We can provide regular backups of your data upon request, we are working on adding configuration options for this feature. **Can I export my data?** Yes, you can export your data and configurations. Contact support for assistance with data export. **Where is my data stored?** Your data is stored in AWS datacenters, Ireland, Europe. We are working on multiregion support. **Do you have compliance certifications?** We’re working on obtaining relevant compliance certifications. Contact us for specific compliance requirements. ## Technical Questions **What’s the difference between components and add-ons?** * **Components**: Application layers (frontend, backend, full-stack) that users can access * **Add-ons**: Services (databases, cache, etc.) that are only accessible to your components **How does the deployment process work?** 1. You create a project with your chosen stack 2. Diploi creates a GitHub repository with starter code 3. You can edit code via browser IDE or locally 4. Changes are automatically deployed when you push to GitHub **Can I use my own Docker images?** Currently, we use pre-configured components, but the Dockerfile for running them is included in your project, so feel free to modify them as you wish, However different component have different requirements to work well. **What ports does my application need to listen on?** Most applications should listen on port 3000 or 8080. Check the specific component documentation for exact requirements. ## Support & Community **How can I get help?** * **Discord**: Join our [Discord community](https://discord.gg/vvgQxVjC8G) * **Email**: Contact us at * **GitHub**: Open an issue in our [documentation repository](https://github.com/diploi/docs) **Do you offer priority support?** Yes, priority support is available for enterprise customers. Contact our sales team for more information. **Can I request new features?** Absolutely! We love hearing from our community: * Share ideas on [Discord](https://discord.gg/vvgQxVjC8G) * Email suggestions to * Open issues on [GitHub](https://github.com/diploi/docs) ## Still Have Questions? If you didn’t find the answer you’re looking for: * **Join our [Discord community](https://discord.gg/vvgQxVjC8G)** for real-time help * **Contact us directly** at We’re here to help and always appreciate feedback on how we can improve our documentation! # Get Started > How to set up a server with components and add-ons. ## Using Diploi When you launch a new Project using Diploi, you get a repository in your GitHub account, which is fully configured. All you need to launch a new Project, is to sign up using a Github account. [Code without local installations and deploy with one click using this platform](https://www.youtube.com/embed/rsnqJ2QzMIY?si=f6jpNevvuOZbxKq6) *** ## Launching a new application When you register, you get access to [the Diploi dashboard](https://console.diploi.com) which allows you to create projects where you can collaborate with your team, connect to remote development environment, and create development, staging, and production deployments. ### Test-driving Diploi You can try out Diploi without registering, by starting a trial from our homepage, visit [diploi.com/#StackBuilder](https://diploi.com/#StackBuilder), select the stack you want to test out and click launch. This will start a trial environment where you can try most features that Diploi has to offer in a development deployment. This deployment stays active for 1 hour and can be claimed by registering an account. #### Starting a trial from the Homepage Quick Launch is the fastest way to get started with Diploi. It allows you to quickly launch a new application online without the need to create a repository or configure anything. You can start a deployment right away from [our homepage](https://diploi.com/#StackBuilder). Tip No registration or credit card needed to get started!  In the stack builder, you can can choose the components and add-ons you want to have in your deployment, and that’s it! You can click “**Launch stack**” and your deployment will be ready in about 30 seconds.  Once the launch is complete, you will be able to connect to the remote server and your deployment will be accessible online with https.  Note Quick Launch is intended to quickly try things out. To save your work in a repository you need to sign up. ### Using Diploi for Production To get started using Diploi for Production apps, you need to create a Diploi account. Since Diploi is tightly integrated with GitHub, you will need a GitHub account to be able to register. To register, go to [console.diploi.com](https://console.diploi.com) and authenticate using your GitHub account. *** For more information on how to use Diploi, check out the following guides: * [Creating a Project](/deploying/creating-a-project/) * [Creating a Deployment](/deploying/creating-a-deployment/) # 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. Note You can have as many components and add-ons in your project as you want 🙂 ### 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 Note This SMTP relay is only reachable from processes running inside your Diploi deployment network. External services cannot connect. ### 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.  Note The stage for your deployment will define if your environment is a dynamic or a build deployment. #### 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 browser 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.  Note The Repository section is only available for projects that are started with a repository. ### 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.  Note Not all components and add-ons have editable settings in this section. ## 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.  Note Depending on the deployment stage of your deployment, the overview page will show different information. **For Development deployments**, the overview will show an additional entry **Development**, which allows you to access the remote development environment using our browser IDE or VS code. ### 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.  Note For deployments that are not for development, you can still access the deployment with SSH [by going to the containers section in the overview page](#connect). ##### 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. Note You will need to add an SSH key to your profile in order to authenticate via SSH. Please see the [Add SSH Key](/building/add-ssh-key/) guide for more information. *** #### 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. Note All add-ons by default are only accesible locally by your applications and are not exposed to the wider internet. #### 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.  Note To connect via SSH to any deployment, you first need to [add your public SSH key to Diploi](/building/add-ssh-key). ##### 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.  Note If you update the name of your deployment, it won’t affect the repository’s name or alter your application’s behavior. #### 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:  Note When you first assign a new domain for your application, it can take up to 30 minutes for the new SSL certificate to become valid. #### 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.  Note If you want to delete an entire project, you must first delete all deployments that belong to the project first. # 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.  Note Using the CLI is currently under development, which is why some of the features mentioned here are not yet available for all users. ## 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. Tip Read our blog post about our [IaC implementation](https://dev.to/diploi/how-we-solved-infrastructure-as-code-2ldn) for more information. ```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. Note If you plan to run staging and production stages for your project in Diploi or you need to customize how a component is run at startup, you will need to add a Dockerfile (used by staging and production deployments) and a Dockerfile.dev (used by development deployments) files to the folder you are pointing to. You can get all of our officially supported Dockerfiles for all components [in our GitHub repositories](https://github.com/orgs/diploi/repositories). ### `package` The URL for the package repository. Version comes after the hashtag `#` symbol. Version can be a Git tag or branch reference. ### `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 ``` Note This feature is only available for supported components. #### `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`). Tip You can get the official Dockerfiles for all Diploi-supported components from the [Diploi GitHub repositories](https://github.com/orgs/diploi/repositories). Each component repository contains the `Dockerfile` and `Dockerfile.dev` used as defaults. ## 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. Note GitHub repository secrets can be added under **Settings → Secrets and variables → Actions** in your repository. # 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** Note Services are not exposed publicly by default. They can only be accessed by the components in your project. *** ### Previewing your Project In this section, you can see a preview of your monorepo folder structure at root level.  Note From the preview, you can rename the folders that contain your components and the add-on names that your application will be using, by clicking on the element you want to edit  ### 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. Note **Using an existing repository and importing an application to Diploi** is not yet an automagically process, but it is possible. If you would like to bring your existing application to Diploi, contact us on [Discord](https://discord.gg/vvgQxVjC8G) or [via email](mailto:hello@diploi.com). For more information about how to use the Import from GitHub feature, [check this article](/deploying/import-from-github). *** ## 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.  Note If you update the name of your project, it won’t affect the repository’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 ```  Tip If you want to set up a custom domain, you can do it from each deployment. For more information, click here [Deploying / custom-domain](/deploying/custom-domain/) ## 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. Note If you want to create a new project with a repository, you can do so by following the steps in our [Creating a Project](/deploying/creating-a-project) guide. ### 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). # Roadmap > Feature roadmap and upcoming improvements for Diploi Here is a short list with item we are currently working on. ### Improved project import Basic support for importing and running existing GitHub repositories was recently added. We now support **Lovable** and some basic **NodeJS** projects. The idea is to gradually expand this support to be able to run as many types of tech stacks as possible, preferably without any configuration. Expect improvements on a monthly basis. Just running any kind of existing repository is a little more tricky for us than eg. Railway or Netlify since we also need to run the system in development preferrably with hot-reloading and all other development specialties working. ### Custom components Custom components will allow power users to create and fine-tune their own components in order to run technologies not currently supported by Diploi. Dipli components and add-ons are based on Helm charts, so this will provide a lot of flexibility. Note **Interested in early access?** If you need this capability now, we might be able to make special arrangements. Please contact us at . ### Inline components We intend to make it possible to include a component’s configuration directly in your source repository, allowing for tight control on exactly how the cluster is configured. This will also be useful for component editors. ### Vertical scaling This will make it possible to use Diploi for applications with more traffic than a single-node cluster can handle, it will also improve availability and reliability. ### Community Requests We’re tracking feature requests from our community. Here are the most requested features: 1. **Multi-language support** - Support for more programming languages 2. **Database migrations** - Automated database schema management 3. **CI/CD integration** - Built-in testing and deployment pipelines 4. **Team management** - Advanced collaboration features 5. **Monitoring & Analytics** - Built-in application monitoring ### How to Request Features Have an idea for a new feature? We’d love to hear from you: * **Discord**: Join our [Discord community](https://discord.gg/vvgQxVjC8G) and share your ideas * **Email**: Send us your suggestions at * **GitHub**: Open an issue in our [documentation repository](https://github.com/diploi/docs) ### Stay Updated To stay informed about new features and updates: * Follow us on [GitHub](https://github.com/diploi) * Join our [Discord community](https://discord.gg/vvgQxVjC8G) * Subscribe to our newsletter * Check our [blog](https://diploi.com/blog) for announcements *** Tip **Have feedback on our roadmap?** We’re always looking to improve our planning and would love to hear your thoughts on our priorities and timeline. # The Diploi Way > The philosophy behind Diploi - Own your Stack, Infrastructure as Code and Remote Development Diploi is based on the three simple principles #### 1. Own your Stack **Keep as much of your project’s tech stack inside Diploi as possible so development matches production.** **Why?** In the beginning it’s tempting to add third-party services to your solution (cloud databases, caching, object-storage, analytics). As teams members and environments (dev, test, staging, prod) multiply, you will need to address how these tools integrate to different deployments. You will need to create instances of the services for each deployment, or leave out or share the data between instances, possibly causing issues. Centralizing common components in Diploi keeps environments repeatable and disposable. ###### Benefits 1. **Environment parity** - All deployments behave the same, fever “works on my machine” issues. 2. **Clonable environments** - Spin up a new environment by cloning another (eg. prod), including databases and other components. 3. **Cost control** - Stop environments when not in use to reduce costs. No need to run test environments 24/7, just start them when needed. 4. **Less DevOps** needed to bring up and down complete environments in seconds ###### When to deviate * A specialized external service is worth the integration overhead. * Diploi doesn’t (yet) support a component you need. * You require scale/features beyond what Diploi currently offers. #### 2. Infrastructure as Code **Keep all your code in one place, structure your project as a monorepo. Keep the tech stack configuration as part of your project.** **Why?** Keeping the infrastructure configuration of a project together with other source code is a good way of having the complete solution under one single roof. Architecture changes will happen automatically, along with code changes as code is committed. In Diploi the building blocks of your solution is stored inside `diploi.yaml` (think “`package.json` for infra”). While preferences differ, many now prefer to structure their code as a monorepo. Diploi encourages this and uses a default setup where the code for each infra component by default lives in a separate folder. ###### Benefits 1. **Visibility & collaboration** - The whole system is versioned and reviewable alongside the app. 2. **Atomic updates** - One PR can change app code, services, and config together. 3. **Easy DevOps** - Modifying the tech stack is easy, just add a few lines to `diploi.yaml`, press save and in a few seconds you’ll have eg. a new database attached to you service. Hot reload for architecture 🤩. #### 3. Remote Development **Develop in the cloud, with zero local setup.** **Why?** Local environments drift, especially across multiple projects. Cloud development gives every contributor a fresh, project-correct toolchain and data snapshot. No more “which Node/Postgres/CLI do I need for this repo?” In Diploi you either develop using our in-browser editor or using your local IDE, but over SSH (Cursor, VSCode, Windsurf, Zed, etc.). You will be able to use all your AI tools and vibe-coding tricks just like you are used to. ###### Upside 1. **Correct by default** - Everyone always have the tools and version for the project you are working on. 2. **No setup time** - Skip local installs, SDKs, and data seeding. New developers are productive in minutes. 3. **Consistent debugging** - Same environment as preview/staging reduces “works locally” issues. ###### Trade-offs * **Connectivity:** Unreliable or no internet is a blocker. Most IDEs handle flaky connections well, but fully offline work isn’t possible * **Ergonomics:** If you once in a while need fully local coding, you can of course still clone locally. # Troubleshooting > Quick fixes and deep-dive guides for common Diploi issues (remote dev, Git, deployments, domains, add-ons). Find the case that matches your situation and follow the checklist. Each section ends with what to collect if you need support. ## Start here * **New issue and you’re not sure where to look?** Start with **[First-aid checklist](#first-aid-checklist)** * **Imported app fails to run?** Go to **[Hosting existing apps from GitHub](#hosting-existing-apps-from-github)** * **Can’t connect to your environment?** Go to **[SSH and Remote Development](#ssh-and-remote-development)** * **Git push/pull/auth problems?** Go to **[Git and GitHub](#git-and-github-issues)** * **Build failed / deploy stuck / wrong version running?** Go to **[Builds and Deployments](#builds-and-deployments)** * **Domain or SSL issues?** Go to **[Custom domains & SSL](#custom-domains-and-ssl)** * **Database/add-on connection errors?** Go to **[Databases & add-ons](#databases-and-add-ons)** * **Slow app / OOM / resource limits?** Go to **[Performance & limits](#performance-and-limits)** * **Other issues not listed in this guide?** Go to **[Getting Help](#getting-help)** Good to know Most issues are commonly caused by runtime errors, which can be found by checking the deployment’s **logs** from the Overview tab. *** ## First-aid checklist The fastest path from “something is broken” to a clear root cause. Try these steps first. They solve most issues in minutes. ### 1. Identify the deployment stage * **Development**: meant for remote development (Browser IDE / VS Code / Cursor / Zed), code is editable live. * **Staging/Production**: runs a built image (CI/CD style), code changes come from a Git branch, and updates when you push updates to said branch.  ### 2. Check status and logs * Open the deployment **Overview** * Look for: * Failing containers/services * Recent restarts * Error lines in the logs of a component * Deployment status shows “possible issues” or an error state ### 3. Confirm what changed * A new dependency? * A change to `diploi.yaml`? * A DNS or domain change? * A framework upgrade? ### 4. Try the smallest rollback * Revert the last change (code or config) * Restart the affected service/deployment * Stop and start the deployment again * If you updated a domain or DNS settings, you need to wait up to 30 minutes for the changes to propagate *** For more specific issues, refer to the cases listed below. In case none of the listed categories fit your situation, check the section showing how [to get help for other issues](#getting-help) and contact our team. *** ## How this guide is structured Each troubleshooting section follows the same pattern: 1. **Symptoms** (what you see) 2. **Fast fixes** (5-10 minutes) 3. **Deep diagnosis** 4. **If still stuck (collect this)**: a copy/paste checklist for support *** ## Hosting existing apps from GitHub Diploi’s automated import feature tries to configure any app you import, but it is not fail-proof. These are some common situations you might find, and how to handle them. ### Symptoms * Import analysis determined that the app could be hosted on Diploi, but the app shows a 502 error or fails to load * Import failed, but the app has a `diploi.yaml` file already or it was created using Diploi * Import analysis finished successfully for a fullstack app, but one of the components fails to start ### Fast fixes #### Reset your deployment Sometimes, the resource allocation API might fail during the startup of your app, which can cause your app to get stuck while trying to start. Try disabling the deployment and enabling it again to run the startup sequence again.  #### Failing components or deployment fails to start In cases when you have a multi-component app, it could be the case that a one of the components fails to start. This could be because ENV variables are missing or there are version conflicts. Check the [builds and deployments](#builds-and-deployments) section which goes over what to do. #### Missing components or add-ons If your app’s stack was not correctly detected, you can manually configure the mising elements by editing the `diploi.yaml` file in the root of your project. For more information about how to use the `diploi.yaml` file, check [this article explaining how to use it](/reference/diploi-yaml). ### Deep diagnosis #### Review deployment logs In most situations, when your import fails to start, it is possible that the import system used the wrong start commands or some files are missing in your repository. To debug these situation, you can view the logs of each component in your app to determine why your app might be failing to start.  ### If still stuck (collect this) * List the components of your app’s stack, eg. Next.js + Deno + Redis + Mongo * Your deployment’s URL, eg. `https://console.diploi.com//project//deployment/` * Describe the issue(s) you found while trying to host an app *** ## SSH and Remote Development For issues related to remote access via SSH to development environments or app containers, via Browser IDE, VS Code, Cursor, Zed, or from a terminal. ### Symptoms * VS Code/Cursor/Zed can’t connect (timeout, permission denied, handshake failed) * SSH prompts keep repeating when you try to connect with your local IDE * Browser IDE works, but local IDE does not * Connection fails when trying to access a container with SSH ### Fast fixes #### Confirm your SSH key is added Follow the SSH key guide and re-check that you pasted the **public** key (the `.pub` content).\ See: [Connecting via SSH](/building/add-ssh-key/) #### Try connecting using SSH from the terminal From the deployment Overview, copy the **Connect via SSH** command and run it locally.  Then use the copied SSH connection string from your terminal, eg, `ssh dev-z8E49384c728@console.diploi.com` * If this fails, when you try connecting from your local IDE, it will also fail. * If this succeeds, the issue is usually local IDE configuration or possibly because your SSH private key has not been added to the SSH agent. #### Windows and WSL If you use Windows with WSL, verify which environment your IDE is using for SSH keys, Windows user, or WSL user. ### Deep diagnosis #### Host key / known\_hosts conflicts If you see messages about a host key changing, remove the old entry from your `~/.ssh/known_hosts` (or use `ssh-keygen -R `), then reconnect. #### Permissions Ensure: * `~/.ssh` has read/write/execute permissions, using the command `chmod 700 ~/.ssh` * Private and public keys must have read/write permissions, using the command `chmod 600 /` for the key pair used. ### If still stuck (collect this) * Exact SSH command you ran * Full terminal output (redact secrets) * Your OS and IDE (VS Code/Cursor) version * Whether Browser IDE works * [Contact us](#where-to-ask) *** ## Git and GitHub issues For issues related to GitHub auth, push/pull failures, and repository access problems in Diploi deployments. ### Symptoms * `fatal: Authentication failed` * `remote: Permission to denied` * The production and Staging environments fail to update ### Fast fixes #### 1. Retry running the git command In some situations, when you try to run a git command, eg, `git pull`, the first try might fail due to connection issues or latency, but in most cases, trying to run the command again can clear the issue. #### 2. Verify that Diploi still has access to the repository If you recently modified Diploi’s access to your repositories, it is possible that the project you are using is no longer in sync with GitHub, which would prevent you from pushing or pulling. To restore access, visit and check if Diploi is still installed in the repository linked to your Diploi project. #### 3. Check that the GitHub actions succeed after pushing an update For situations when your Staging or Production environments show a version of your application which is not the latest, check that the branch where you pushed your updates has run an action and is marked as successful.  Diploi uses GitHub Actions to create builds of your application for Development and for Staging/Production. ### Deep diagnosis #### Your project was initiated without a repository If you started a project without a repository, and you use git init or clone a repository inside the repository, then any authentication you add to sync with GitHub won’t be managed by Diploi, so if you create new deployments, you’ll need to manually authenticate in GitHub in order to sync your code. ### If still stuck (collect this) * The command you ran (`git fetch`, `git push`, etc.) * The exact error output * Whether this is a Development deployment or a Staging/Production stage * Whether the deployment has an assigned user * [Contact us](#where-to-ask) *** ## Builds and Deployments Troubleshoot failed builds, stuck rollouts, wrong version running, and unhealthy services. ### Symptoms * Deployment stuck on “starting” / “Initializing” / “Possible issues” / “Error” * App is up, but is not showing the latest commit * One component/add-on fails to run or restarts constantly * Staging/production doesn’t reflect `diploi.yaml` changes ### Fast fixes #### 1. Confirm deployment type * Development deployments are optimized for remote dev * Staging/Production deployments run a built image #### 2. Check the deployment status tree and service logs Inspect the failing components/add-ons and check their logs, looking for errors. If the components and add-ons seem to be working correctly, but your application still shows errors, open the live view of each component with the browser Developer Tools open. Check the console and network tabs to find any potential issues preventing your application from running. #### 3. Verify that the ports used in your application config match the Dockerfile settings If you configured the ports used by a component or add-on in your application, make sure to update them inside the `Dockerfile` (for Staging/Production) and the `Dockerfile.dev` (for Development environments). #### 4. Verify your CI/CD run If your project’s GitHub Action didn’t run or at least one of the builds failed, the deployment will remain on the last build where all components were successful. You can find the issues with your GitHub Actions by reviewing the execution logs of the action. ### Deep diagnosis #### Config changes (`diploi.yaml`) not taking effect * Confirm that the `diploi.yaml` file is in the repo and committed * Confirm that the change is on the branch tied to the deployment * Make sure to apply any changes from your `diploi.yaml` file to your deployment, and then push the changes to your repository  #### Other common failure patterns ##### GitHub Action build fails * Check the GitHub Action’s workflow run logs * Make sure that dependency changes are part of the lockfiles of your components, eg, for Python `uv.lock`, for JS `package-lock.json`  ##### Build succeeds, but runtime fails * Make sure that all necessary ENV variables are defined * If your components require add-ons to operate, make sure to run the necessary migrations and that the add-ons are reachable * If you made changes to a component and now use a different run command, update it inside the `Dockerfile` and `Dockerfile.dev` belonging to the component ### If still stuck (collect this) * Deployment stage and name * Link to the CI run (if it’s a public repository) * Logs from the failing service (include startup section) * What changed (code/config/add-ons) * [Contact us](#where-to-ask) *** ## Custom domains and SSL For issues linked to DNS records, propagation, and SSL provisioning issues for custom and Diploi domains. ### Symptoms * After changing a deployment’s domain, the app fails to render * DNS works for `www` but not apex/root * SSL pending or browser certificate warning * Domain verified in one place (DNS) but not in Diploi ### Fast fixes #### 1. Verify the record type and target * Subdomain usually uses a **CNAME** pointing to `edge.diploi.me` * Ensure the **name/host** matches the subdomain you intended #### 2. Wait for DNS propagation Use your DNS provider UI to confirm the change is saved and active. Changes to DNS records can take up to 30 minutes to propagate. #### 3. Apex/root domains Some providers need ALIAS/ANAME-style records for apex domains. Make sure to assign the right record type. For more information about record types, check our article listing the types of records supported based on the provider you use: [Configuring a custom root domain](/deploying/custom-domain#configuring-a-custom-root-domain). #### 4. Verify your application’s endpoints are not hardcoded or defaulting to use http If you use hardcoded endpoints within your application, remember to update them to match your new domain, and verify that they use https by default. In Diploi, both custom and autogenerated domains are SSL-protected by default. Note If your provider only supports A records at the root, document what you tried and contact us. ### Deep diagnosis #### Wrong environment bound to the domain Diploi supports domains at both project and deployment levels. Verify you added it to the intended level. ### If still stuck (collect this) * Domain name and record screenshots * Which DNS provider do you use * Whether it’s project-level or deployment-level domain * Timestamp when you updated DNS *** ## Databases and add-ons Fixing connection issues, missing env vars, and common configuration mistakes with add-ons like Postgres/Redis/Mongo/MariaDB/MinIO. ### Symptoms * “Connection refused” * “password authentication failed” * App starts, but features using the DB fail * Works in dev, fails in staging/prod (or vice versa) ### Fast fixes #### 1. Confirm the add-on is running and healthy Check the deployment Overview status tree and the add-on logs.  #### 2. Confirm if your app imports env variables from the deployment or from a .env file If your application is using both an `.env` file and the environment variables of the deployment, your application might have conflicting duplicate variable declarations. Make sure to only use one source for your environment variables. We recommend that you keep your variables declared with the deployment environment variables.  #### 3. Trying to connect to an Add-on from a service or API outside of your deployment Add-ons hosted on Diploi are not accessible to services outside of the deployment they belong to. If you want to make data accessible to external services, you need to create a broker service that would handle requests on behalf of the add-on you want to access. ### Deep diagnosis #### Migrations/schema init If the DB is reachable but your app still errors, check whether migrations ran and whether they’re expected to run during startup. ### If still stuck (collect this) * Add-on type and identifier * Failing error message and stack trace * Add-on logs around startup * [Contact us](#where-to-ask) *** ## Performance and limits Issues related to slow apps, out-of-memory(OOM) states, and deployment crashes due to high resource load and usage. ### Symptoms * Slow responses/timeouts * Container shuts down/OOM/crash loops under load * Deploy show state as “running” but none of the container logs are visible and endpoints fail to load * Works in Development but not Production ### Fast fixes #### 1. Check resource graphs and container restarts Look for spikes, sustained high usage, or repeated restarts.  #### 2. Increase deployment size or split into multiple deployments In situations where you are running heavy workloads or running many components/add-ons in one deployment, the resource needs of the deployment can rise and cause Kubernetes to kill all containers in the deployment. Try increasing the size of the cluster that your deployment uses or splitting your application into multiple projects.  #### 3. API connections break due to 504 Gateway Timeout, proxy timeout, or idle timeout **Diploi has a connection length limit per request/response processed by a service of 60 seconds**. If a request takes more than 60 seconds to be handled, the connection will be terminated, and your process waiting for a response will fail. In cases when a request could take longer than 60 seconds, we recommend you add pooling or a webhook to send the response to a request when the service is ready. ### Deep diagnosis #### Performance issues during cold starts or while running If your deployment is slow during start-up only, it could be due to the size of the build image and might not affect the actual running performance of your application. This is common for deployments with n8n, Supabase, and/or Ghost components, which can consume a large share of resources during startup, compared with other of our supported components. #### Performance issues during cold starts or while running If your deployment experiences slow performance exclusively during cold starts, it is usually due to the containerization process and **cannot be significantly improved**. This **does not impact the actual running performance** of your application once initialized. You might notice this with resource-intensive components like n8n, Supabase, or Ghost during startup. For cases when runtime performance is the issue, try optimizing your application’s architecture: * Use database indexes and caching strategies * Minimize synchronous operations during request handling * Check if third-party services are causing bottlenecks The main point to note is that cold-start delays might be unavoidable for some components, while runtime performance is directly influenced by your application’s design and configuration. ### If still stuck (collect this) * Average traffic volume * CPU/RAM utilization * Logs from the components and/or add-ons where timeouts and out-of-memory events happened * [Contact us](#where-to-ask) *** ## Getting help In case your situation is not included in the listed issues above, or this guide is not enough to handle the issue you encountered, here we list some general information you can share with us to handle your support request faster. ### Before you reach out Make sure you’ve done: * [First-aid checklist](#first-aid-checklist) * Collected logs and exact error(s) text * Include any additional details which are relevant to your issue ### What to include * Project ID * console.diploi.com/*USERNAME*/project/**PROJECT\_ID** * Deployment ID * console.diploi.com/*USERNAME*/project/*PROJECT\_ID*/deployment/**DEPLOYMENT\_ID** * Description of the issue and expected behavior * Steps to reproduce the issue * Logs (20-50 lines) showing the errors triggered * Your Diploi username or GitHub account ### Where to ask You can contact us directly via email or by messaging us in our [Discord community](https://discord.com/invite/vvgQxVjC8G)