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