# Diploi documentation The documentation of Diploi (https://docs.diploi.com) as one text. Every "# " heading is a page (its navigation path, then the page url on a "Source:" line and its summary), the headings below it are the sections of that page. # Introduction Source: https://docs.diploi.com/ > 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 [![](https://diploi.b-cdn.net/component/diploi/component-asp/icon.svg?ref=main)**ASP.NET**](/building/components/asp)[![](https://diploi.b-cdn.net/component/diploi/component-astro/icon.svg?ref=main)**Astro**](/building/components/astro)[![](https://diploi.b-cdn.net/component/diploi/component-blazor/icon.svg?ref=main)**Blazor**](/building/components/blazor)[![](https://diploi.b-cdn.net/component/diploi/component-bun/icon.svg?ref=main)**Bun**](/building/components/bun)[![](https://diploi.b-cdn.net/component/diploi/component-deno/icon.svg?ref=main)**Deno**](/building/components/deno)[![](https://diploi.b-cdn.net/component/diploi/component-django/icon.svg?ref=main)**Django**](/building/components/django)[![](https://diploi.b-cdn.net/component/diploi/component-fastapi/icon.svg?ref=main)**FastAPI**](/building/components/fastapi)[![](https://diploi.b-cdn.net/component/diploi/component-flask/icon.svg?ref=main)**Flask**](/building/components/flask)[![](https://diploi.b-cdn.net/component/diploi/component-ghost/icon.svg?ref=main)**Ghost**](/building/components/ghost)[![](https://diploi.b-cdn.net/component/diploi/component-hono/icon.svg?ref=main)**Hono**](/building/components/hono)[![](https://diploi.b-cdn.net/component/diploi/component-laravel/icon.svg?ref=main)**Laravel**](/building/components/laravel)[![](https://diploi.b-cdn.net/component/diploi/component-n8n/icon.svg?ref=main)**n8n**](/building/components/n8n)[![](https://diploi.b-cdn.net/component/diploi/component-nextjs/icon.svg?ref=main)**Next.js**](/building/components/next)[![](https://diploi.b-cdn.net/component/diploi/component-nodejs/icon.svg?ref=main)**Node.js**](/building/components/node)[![](https://diploi.b-cdn.net/component/diploi/component-python/icon.svg?ref=main)**Python**](/building/components/python)[![](https://diploi.b-cdn.net/component/diploi/component-react-vite/icon.svg?ref=main)**React + Vite**](/building/components/react-vite)[![](https://diploi.b-cdn.net/component/diploi/component-static/icon.svg?ref=main)**Static Website**](/building/components/static)[![](https://diploi.b-cdn.net/component/diploi/component-supabase/icon.svg?ref=main)**Supabase**](/building/components/supabase)[![](https://diploi.b-cdn.net/component/diploi/component-sveltekit/icon.svg?ref=main)**SvelteKit**](/building/components/sveltekit)[![](https://diploi.b-cdn.net/component/diploi/component-tanstack-start/icon.svg?ref=main)**TanStack Start**](/building/components/tanstack-start) #### Add-ons available [![](https://diploi.b-cdn.net/component/diploi/addon-mariadb/icon.svg?ref=main)**MariaDB**](/building/add-ons/mariadb)[![](https://diploi.b-cdn.net/component/diploi/addon-minio/icon.svg?ref=main)**MinIO**](/building/add-ons/minio)[![](https://diploi.b-cdn.net/component/diploi/addon-mongo/icon.svg?ref=main)**MongoDB**](/building/add-ons/mongo)[![](https://diploi.b-cdn.net/component/diploi/addon-postgres/icon.svg?ref=main)**PostgreSQL**](/building/add-ons/postgres)[![](https://diploi.b-cdn.net/component/diploi/addon-redis/icon.svg?ref=main)**Redis**](/building/add-ons/redis) #### Starter kits available [![](https://diploi.b-cdn.net/component/diploi/starter-openclaw/icon.svg?ref=main)**OpenClaw Assistant**](/building/starter-kits/openclaw)[![](https://diploi.b-cdn.net/component/diploi/starter-chat/icon.svg?ref=main)**Chat App**](/building/starter-kits/chat)[![](https://diploi.b-cdn.net/component/diploi/starter-refine-pixels/icon.svg?ref=main)**Collaborative Drawing App**](/building/starter-kits/refine-pixels)[![](https://diploi.b-cdn.net/component/diploi/starter-web-app/icon.svg?ref=main)**Web App**](/building/starter-kits/web-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 cloud IDE. In that case you need to add your SSH key to Diploi in order for remote access to work. ## How it Works Diploi uses a configuration-in-code approach to spin up every deployment as a separate single-node Kubernetes cluster (Don’t worry, you need zero Kubernetes knowledge to use Diploi). Diploi takes care of hostnames, SSL certificates, building and updating Docker images for each service and making it easy to code right on the cluster, aiming for the best possible DX. Diploi works best when you set up your project as a monorepo, where the code for every component lives in a separate folder. If you are interested in more details and reasons for these choices, please see [Technical Deep Dive](/reference/technical-deep-dive/) ## Get started The easiest way to learn Diploi is by launching a new application. For a quick walkthrough [Get Started](/get-started/) here, no registration needed. Note When you create and register you get 50€ in credits so you can get the full Diploi experience at no cost for 14 days. **No credit card required**. After the trial you are charged based on used resources, see [pricing](https://diploi.com/pricing). # Introduction › Get Started Source: https://docs.diploi.com/get-started > How to set up a server with components and add-ons. ## Using Diploi When you launch a new Project using Diploi, you get a repository in your GitHub account, which is fully configured. All you need to launch a new Project, is to sign up using a Github account. [Code without local installations and deploy with one click using this platform](https://www.youtube.com/embed/rsnqJ2QzMIY?si=f6jpNevvuOZbxKq6) *** ## Launching a new application When you register, you get access to [the Diploi dashboard](https://console.diploi.com) which allows you to create projects where you can collaborate with your team, connect to remote development environment, and create development, staging, and production deployments. ### Test-driving Diploi You can try out Diploi without registering, by starting a trial from our homepage, visit [diploi.com/#StackBuilder](https://diploi.com/#StackBuilder), select the stack you want to test out and click launch. This will start a trial environment where you can try most features that Diploi has to offer in a development deployment. This deployment stays active for 1 hour and can be claimed by registering an account. #### Starting a trial from the Homepage Quick Launch is the fastest way to get started with Diploi. It allows you to quickly launch a new application online without the need to create a repository or configure anything. You can start a deployment right away from [our homepage](https://diploi.com/#StackBuilder). Tip No registration or credit card needed to get started! ![Quick launch builder](/_astro/QuickStartBuilder.Ca2WLg3T_1Y26vP.png) 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. ![Quick launch loading](/_astro/QuickLaunchLoading.CIBy5kwo_ZU9KdP.png) Once the launch is complete, you will be able to connect to the remote server and your deployment will be accessible online with https. ![Quick launch home](/_astro/QuickLaunchHome.CZE4n8XZ_tvsRa.png) Note Quick Launch is intended to quickly try things out. To save your work in a repository you need to sign up. ### Using Diploi for Production To get started using Diploi for Production apps, you need to create a Diploi account. Since Diploi is tightly integrated with GitHub, you will need a GitHub account to be able to register. To register, go to [console.diploi.com](https://console.diploi.com) and authenticate using your GitHub account. *** For more information on how to use Diploi, check out the following guides: * [Creating a Project](/deploying/creating-a-project/) * [Creating a Deployment](/deploying/creating-a-deployment/) # Introduction › The Diploi Way Source: https://docs.diploi.com/the-diploi-way > The philosophy behind Diploi - Own your Stack, Infrastructure as Code and Remote Development Diploi is based on the three simple principles #### 1. Own your Stack **Keep as much of your project’s tech stack inside Diploi as possible so development matches production.** **Why?** In the beginning it’s tempting to add third-party services to your solution (cloud databases, caching, object-storage, analytics). As teams members and environments (dev, test, staging, prod) multiply, you will need to address how these tools integrate to different deployments. You will need to create instances of the services for each deployment, or leave out or share the data between instances, possibly causing issues. Centralizing common components in Diploi keeps environments repeatable and disposable. ###### Benefits 1. **Environment parity** - All deployments behave the same, fever “works on my machine” issues. 2. **Clonable environments** - Spin up a new environment by cloning another (eg. prod), including databases and other components. 3. **Cost control** - Stop environments when not in use to reduce costs. No need to run test environments 24/7, just start them when needed. 4. **Less DevOps** needed to bring up and down complete environments in seconds ###### When to deviate * A specialized external service is worth the integration overhead. * Diploi doesn’t (yet) support a component you need. * You require scale/features beyond what Diploi currently offers. #### 2. Infrastructure as Code **Keep all your code in one place, structure your project as a monorepo. Keep the tech stack configuration as part of your project.** **Why?** Keeping the infrastructure configuration of a project together with other source code is a good way of having the complete solution under one single roof. Architecture changes will happen automatically, along with code changes as code is committed. In Diploi the building blocks of your solution is stored inside `diploi.yaml` (think “`package.json` for infra”). While preferences differ, many now prefer to structure their code as a monorepo. Diploi encourages this and uses a default setup where the code for each infra component by default lives in a separate folder. ###### Benefits 1. **Visibility & collaboration** - The whole system is versioned and reviewable alongside the app. 2. **Atomic updates** - One PR can change app code, services, and config together. 3. **Easy DevOps** - Modifying the tech stack is easy, just add a few lines to `diploi.yaml`, press save and in a few seconds you’ll have eg. a new database attached to you service. Hot reload for architecture 🤩. #### 3. Remote Development **Develop in the cloud, with zero local setup.** **Why?** Local environments drift, especially across multiple projects. Cloud development gives every contributor a fresh, project-correct toolchain and data snapshot. No more “which Node/Postgres/CLI do I need for this repo?” In Diploi you either develop using our cloud IDE or using your local IDE, but over SSH (Cursor, VSCode, Windsurf, Zed, etc.). You will be able to use all your AI tools and vibe-coding tricks just like you are used to. ###### Upside 1. **Correct by default** - Everyone always have the tools and version for the project you are working on. 2. **No setup time** - Skip local installs, SDKs, and data seeding. New developers are productive in minutes. 3. **Consistent debugging** - Same environment as preview/staging reduces “works locally” issues. ###### Trade-offs * **Connectivity:** Unreliable or no internet is a blocker. Most IDEs handle flaky connections well, but fully offline work isn’t possible * **Ergonomics:** If you once in a while need fully local coding, you can of course still clone locally. # Deploying › Creating a Project Source: https://docs.diploi.com/deploying/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: ![Create a project diagram](/_astro/CreateProjectDiagram.DO-9rNPJ_Z1O06iO.svg) ## Creating the Stack for a Project In Diploi, a project refers to a combination of **components** and **add-ons** (also called **services**) that form the **stack** that will make up your application. Note After you create a Project, you can change the stack of your project by editing the `diploi.yaml` in your project’s repository. For more information on how to do this, check out the [Diploi YAML documentation](/reference/diploi-yaml/) To create a project for your app click **Create Project** from your dashboard: `https://console.diploi.com//projects` Which will open the **Stack Builder** where you can choose the components and add-ons for your project. ### Selecting Components ![Project components](/_astro/CreateProjectComponents.BsGNnZs4_Z629cv.png) ### Selecting Add-ons ![Project add-ons](/_astro/CreateProjectAddons.DoZvxdrS_Z1x16gX.png) Note Your project requires at least one component to be selected Once you have chosen the stack for your project, you will be able to see a preview of your selected stack. ### Stack Preview ![Create a project example](/_astro/CreateProjectPreview.Dib1Ltua_21J97h.png) 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. ![Create a project example](/_astro/CreateProjectEditNames.CB7Lv93s_XxGW4.png) ### 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). ![Create a project repo](/_astro/CreateProjectRepo.Do5EVvK9_Z2nxjjA.png) 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. # Deploying › Creating a Deployment Source: https://docs.diploi.com/deploying/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 cloud IDE, or connect directly to the server via SSH. For more about remote development, check out our [Remote Development guide](/building/remote-development/). * **Staging** to test your application and ensure stability before launching changes in your application to production. * **Production** to launch your application when it is ready to be used by your end users. Note When you create a new development deployment, it will be active for 12 hours, after which it will be automatically shut down to avoid unnecessary costs. For staging and production deployments are not started with a time limit, and will remain active until you shut them down manually. ### Choosing a Deployment Size Once you choose the type of deployment you need, choose the size that the deployment should have. The available deployment sizes include: \- **XS** - 2 vCPUs and 2 GB of ram - **0,006 €/hour** \- **S** - 2 vCPUs and 4 GB of ram - **0,014 €/hour** \- **M** - 2 vCPUs and 8 GB of ram - **0,048 €/hour** \- **L** - 4 vCPUs and 16 GB of ram - **0,089 €/hour** \- **XL** - 8 vCPUs and 32 GB of ram - **0,182 €/hour** ![Deployment size](/_astro/CreateDeploymentSize.Dfgzs_1Q_Z1FkIfw.png) Once you have configured the type and size of your deployment, you can click on the **Create Deployment** button to start your deployment. ## Connecting via SSH to a Deployment If you need to connect via SSH to your deployment, you can do it by getting the SSH connection string from the “Components” and “Add-ons” sections found at the bottom of the “Overview” tab of your deployment, found at: `https://console.diploi.com//project//deployment/` Note Your development environment and, each component and add-on of your app’s stack are running on independent containers. From there, you can copy the SSH connection string for the component or add-on you want to connect to by clicking on the “Connect +” button next to the component or add-on. For more information on how to connect to your deployment via SSH, check out our [SSH guide](/building/add-ssh-key/). ![Connect to deployment with SSH](/_astro/CreateDeploymentConnect.BMKmN1OH_ZUH01k.png) *** ## 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. ![Shutdown deployment](/_astro/DisableDeploymentCard.yJ5W_rmx_Z11uOpR.png) Alternatively, you can also shutdown a deployment by clicking on the “enabled” switch found at the top of your Deployment’s status page. ![Shutdown switch](/_astro/DisableDeploymentSwitch.Bf_4-l1j_22lyVQ.png) 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. ![Restart deployment](/_astro/EnableDeployment.BNAFhLoR_Z1SyCM5.png) Note When you shutdown a deployment, it will not generate any costs, you are only charged for the time that your deployment is active. # Deploying › Hosting existing apps Source: https://docs.diploi.com/deploying/import-from-github > 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 ![Click on start new project](/_astro/StartAProject.Isp4kUS4_145DEW.png) 2. Then switch from “Start From Scratch” to the “Import Repository” tab ![Default import for applications that are not fully supported](/_astro/SwitchTabToImport.DLOq6Zl-_Z1T43tm.png) 3. Now you can select the source code you want to import. You can either select a repository stored in your own GitHub account or use a URL to import a public repo. Note You can also import your own repositories via URL, as long as you have approved Diploi to have access to them or if they are public. ![Installing Diploi on specific repos](/_astro/GitHubRepoAccess.DNSwQOtr_Z277nrz.png) 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. ![Analyze repository before importing a project](/_astro/AnalyzeRepository.CKE2tA0q_22nb4X.png) The import system will run an automated analysis, and conclude if your project can be hosted on Diploi or not. ![Analyzing the contents of an application](/_astro/AnalyzingRepository.BCuq2d5K_Z1C6InU.png) Note In cases when Diploi can’t automatically host your imported app, the import result will notify you the reasons why it can’t be configured. ![Failed import summary](/_astro/FailedImportResult.DTdd4-Hz_Z1S3fWF.png) If you need support to import projects, contact us [via email](mailto:hello@diploi.com) or in [Discord](https://discord.com/invite/vvgQxVjC8G). Tip As mentioned before, any repository created using Diploi can be imported without additional configuration required. ![Importing a project built with Diploi](/_astro/RepositoryCreatedWithDiploiImport.Bd8FGMQr_1xpqLt.png) 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. ![Successful import and next steps](/_astro/SuccessImportResult.Da59tDnS_ZstY46.png) 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). ![Configuration summary for an imported project, ready to be launched](/_astro/ImportRepoFinalConfig.WYQfpUO__ZJMlMD.png) 6. Now you should have a development deployment running. If your project is not loading properly or fails to start, check the deployment logs. Tip Diploi uses default port configurations for all supported frameworks and databases, so if your application uses other ports, try first changing your ports to match the ones used by Diploi. You can find the default port config by opening the `Dockerfile.dev` from the remote development environment. ### Other considerations #### Run command config By default, Diploi will use common run commands for development and staging/production deployments, so there might be some situations when your imported application might fail because your project uses different run commands. To handle these situations, you can either modify the `Dockerfile` and `Dockerfile.dev` created by diploi, or modify your app’s config to include the commands used by Diploi to run your application. #### Importing an external public repository When you can import a publicly available repository, which doesn’t belong to your GitHub account, you will have the option of creating a new repository in your account to store your code or start a project without a repository. In case you choose to proceed without a repo, your project won’t be able to start a Production or Staging deployment, because Diploi creates a [GitHub Actions workflow](/reference/github-action/) which takes care of creating a build of your project, which can be ran in Staging and Production. Caution You cannot add a repository to an existing project. If you need to import an application and link it to a new repository, you will need to go through the process of importing the app again and then create a new repository before launching the project. For more information about the differences between projects with or without a repository, [check this article going over their properties](/reference/projects/project#project-types). #### Importing an app from a repository you own When you import from a repo you own, Diploi will use the same repository by default to store your code, so any changes you make to your project can be pushed to the same repository you imported from. Currently, you can’t import a repository and save it in a new repository. Note Once you import an application, you will need to push the files that Diploi creates in your project directly to the `main` branch of your repository. This is needed because Diploi uses Docker in the background to host your application, and it uses a [GitHub Actions workflow](/reference/github-action/) to generate a Docker build that can be used by Diploi. ## Supported Applications Although it is technically possible to import any application, not every app will work right away, and they might require additional work in order to run properly after you import them to Diploi. You can **import any application built with Diploi**, or with any of these frameworks, databases, and technologies: #### Components available [![](https://diploi.b-cdn.net/component/diploi/component-asp/icon.svg?ref=main)**ASP.NET**](/building/components/asp)[![](https://diploi.b-cdn.net/component/diploi/component-astro/icon.svg?ref=main)**Astro**](/building/components/astro)[![](https://diploi.b-cdn.net/component/diploi/component-blazor/icon.svg?ref=main)**Blazor**](/building/components/blazor)[![](https://diploi.b-cdn.net/component/diploi/component-bun/icon.svg?ref=main)**Bun**](/building/components/bun)[![](https://diploi.b-cdn.net/component/diploi/component-deno/icon.svg?ref=main)**Deno**](/building/components/deno)[![](https://diploi.b-cdn.net/component/diploi/component-django/icon.svg?ref=main)**Django**](/building/components/django)[![](https://diploi.b-cdn.net/component/diploi/component-fastapi/icon.svg?ref=main)**FastAPI**](/building/components/fastapi)[![](https://diploi.b-cdn.net/component/diploi/component-flask/icon.svg?ref=main)**Flask**](/building/components/flask)[![](https://diploi.b-cdn.net/component/diploi/component-ghost/icon.svg?ref=main)**Ghost**](/building/components/ghost)[![](https://diploi.b-cdn.net/component/diploi/component-hono/icon.svg?ref=main)**Hono**](/building/components/hono)[![](https://diploi.b-cdn.net/component/diploi/component-laravel/icon.svg?ref=main)**Laravel**](/building/components/laravel)[![](https://diploi.b-cdn.net/component/diploi/component-n8n/icon.svg?ref=main)**n8n**](/building/components/n8n)[![](https://diploi.b-cdn.net/component/diploi/component-nextjs/icon.svg?ref=main)**Next.js**](/building/components/next)[![](https://diploi.b-cdn.net/component/diploi/component-nodejs/icon.svg?ref=main)**Node.js**](/building/components/node)[![](https://diploi.b-cdn.net/component/diploi/component-python/icon.svg?ref=main)**Python**](/building/components/python)[![](https://diploi.b-cdn.net/component/diploi/component-react-vite/icon.svg?ref=main)**React + Vite**](/building/components/react-vite)[![](https://diploi.b-cdn.net/component/diploi/component-static/icon.svg?ref=main)**Static Website**](/building/components/static)[![](https://diploi.b-cdn.net/component/diploi/component-supabase/icon.svg?ref=main)**Supabase**](/building/components/supabase)[![](https://diploi.b-cdn.net/component/diploi/component-sveltekit/icon.svg?ref=main)**SvelteKit**](/building/components/sveltekit)[![](https://diploi.b-cdn.net/component/diploi/component-tanstack-start/icon.svg?ref=main)**TanStack Start**](/building/components/tanstack-start) #### Add-ons available [![](https://diploi.b-cdn.net/component/diploi/addon-mariadb/icon.svg?ref=main)**MariaDB**](/building/add-ons/mariadb)[![](https://diploi.b-cdn.net/component/diploi/addon-minio/icon.svg?ref=main)**MinIO**](/building/add-ons/minio)[![](https://diploi.b-cdn.net/component/diploi/addon-mongo/icon.svg?ref=main)**MongoDB**](/building/add-ons/mongo)[![](https://diploi.b-cdn.net/component/diploi/addon-postgres/icon.svg?ref=main)**PostgreSQL**](/building/add-ons/postgres)[![](https://diploi.b-cdn.net/component/diploi/addon-redis/icon.svg?ref=main)**Redis**](/building/add-ons/redis) Note You can modify your application’s tech stack [from the `diploi.yaml` file](/reference/diploi-yaml). ### Apps built on Diploi Any application built on Diploi can be imported into a new project without any additional configuration. Diploi will provision any component and add-on specified in the `diploi.yaml` file, but with the caveat that any environment variables used in the project must then be set manually, since Diploi doesn’t store the project’s secrets on GitHub. ![Additional example importing an app built with Diploi](/_astro/RepositoryCreatedWithDiploiImport2.MsIfIfYq_11MGf7.png) Note Any changes to component and/or add-on identifiers and root folders can break the base configuration of a project imported, so remember to update any references that have changed. ### Apps built on Lovable If you built a project on Lovable, you can seamlessly import it to Diploi. All you need to do is sync your application on GitHub. For Lovable projects using Supabase, you can use the open-source version of Supabase that is available on Diploi. You can add Supabase by adding the snippet to your `diploi.yaml` file. ```plaintext - name: Supabase identifier: supabase package: https://github.com/diploi/component-supabase#main ``` Paste the snippet within the `components` field in the `diploi.yaml`, usually found in the root of your project. ```plaintext components: - name: Lovable ... - name: Supabase identifier: supabase package: https://github.com/diploi/component-supabase#main ``` If you would like a detailed walkthrough about how to import an application built with Lovable, [click here to check our tutorial explaining how to do it](https://diploi.com/blog/importing_from_lovable_and_github). We also have a guide walkthrough explaining how to use Cursor for your imported Lovable app, which [you can check by clicking here](https://diploi.com/blog/exporting_from_lovable_to_cursor). Tip To add additional frameworks and databases to your imported Lovable app, add the components and add-ons you would like by modifying the `diploi.yaml` file. [Click here for more information about how to do it](/reference/diploi-yaml). #### Running Supabase Migrations after Importing a Lovable App If you are using the Lovable project with Supabase, you’ll need to run the necessary migrations, which should be stored inside your Supabase folder, as `migrations`. You can apply the migrations to your new Supabase instance by running the command `supabase migration up` from the development environment created when you import the project. Tip Besides `npm`, Diploi also supports `yarn` and `pnpm` as package managers. For Python-based applications, currently we support `uv`, but you can also import apps that use venv and pip. # Deploying › Cloning a Deployment Source: https://docs.diploi.com/deploying/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` ![Cloning a deployment](/_astro/CloningAction.Cl4E7AiM_ZCEf0j.png) Look for the **Clone Deployment** section, and there you can click on the **Clone this deployment** button to launch the deployment cloning wizard, which is very similar to the deployment creation workflow. Keep in mind During the process of cloning, you will be unable to make changes to the deployment. ![Confirming the start of a cloning operation](/_astro/CloningDialogConfirmation.oh0_-ZJM_ZEXR8X.png) ### 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. ![Clone deployment stage selection](/_astro/CloningDeploymentStage.B7C6cPkz_2h2w8U.png) For more information about the types of deployment stages, check [this article, which explains the differences between each type](/reference/deployments/deployment-lifecycle#deployment-stage). Note When you create a new development deployment, it will be active for 12 hours, after which it will be automatically shut down to avoid unnecessary costs. For staging and production deployments, they are not started with a time limit, and will remain active until you shut them down manually. ### Selecting the Deployment Size After assigning the stage for the cloned deployment, you can choose the size that the deployment should have. The available deployment sizes include: \- **XS** - 2 vCPUs and 2 GB of ram - **0,006 €/hour** \- **S** - 2 vCPUs and 4 GB of ram - **0,014 €/hour** \- **M** - 2 vCPUs and 8 GB of ram - **0,048 €/hour** \- **L** - 4 vCPUs and 16 GB of ram - **0,089 €/hour** \- **XL** - 8 vCPUs and 32 GB of ram - **0,182 €/hour** ![Deployment size](/_astro/CreateDeploymentSize.Dfgzs_1Q_Z1FkIfw.png) ### Configuring Environment Variables Clone deployments inherit their Env values from the source deployment, which you can modify before launching the deployment. ![Environment variables for a cloned deployment](/_astro/DeploymentEnvVars.BZ4gR8uC_Z26Elrp.png) ### 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. ![Starting a clone deployment](/_astro/LaunchClonedDeployment.DzM85TUn_22DRTP.png) Note There’s no difference between cloned and non-cloned deployments in terms of how they operate. So you can expect it to behave exactly as any other deployment. # Deploying › Adding Custom Domains Source: https://docs.diploi.com/deploying/custom-domain > 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. ![Applying a custom domain](/_astro/ProjectOptionsDomain.BP4iVfxG_Z25RT88.png) Note Depending on your domain hosting service, the configuration above might use different terminology. If anything was unclear or you need help, talk with us on [Discord](https://discord.gg/vvgQxVjC8G) or [contact us](mailto:hello@diploi.com). ### Configuring a Custom Root Domain e.g. `example.com` Root domains (also called apex or base domains) do not officially support CNAME records, which Diploi needs. Many DNS providers offer similar functionality with custom record types like ALIAS or ANAME.\ To point an apex domain to Diploi, you should refer to your DNS providers own instructions.\ We have created a table which lists the recommended records to use with some of the most popular DNS providers: | Provider | Record | Value | | ------------- | ------ | ---------------- | | Cloudflare | CNAME | `edge.diploi.me` | | DNS Made Easy | ANAME | `edge.diploi.me` | | DNSimple | ALIAS | `edge.diploi.me` | | DreamHost | ALIAS | `edge.diploi.me` | | easyDNS | ANAME | `edge.diploi.me` | | Namecheap | ALIAS | `edge.diploi.me` | | PointDNS | ALIAS | `edge.diploi.me` | | Porkbun | ALIAS | `edge.diploi.me` | Note Depending on the DNS provider, an empty or `@` value usually identifies the root domain. So instead of adding a record for `example.com`, it might need to be added to `@` e.g. Note If your DNS provider only supports A records for root domains, please react out to us. We can offer assistance with configuration. # Deploying › Resizing Disk Storage Source: https://docs.diploi.com/deploying/resize-disk > 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. ![Disk usage monitor with Resize button](/_astro/ResizeDisk.BnVMVoKf_Z1J6CUC.png) *** ## 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. ![Resize Disk dialog](/_astro/ResizeDiskAction.Cf1k7k51_Z1qnUmQ.png) 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. ![Recalculating the storage costs](/_astro/StorageCostCalculator.PP4U8ZXu_1f4IpJ.png) Once you have selected the desired size, click the **Resize** button to confirm. The additional storage will be made available to your deployment. Note Resizing does not require your deployment to be paused or restarted. Your application will continue running during the resize operation. *** ## See also * [Creating a Deployment](/deploying/creating-a-deployment) * [Deployment Lifecycle](/reference/deployments/deployment-lifecycle) # Building › Using Components Source: https://docs.diploi.com/building/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 [![](https://diploi.b-cdn.net/component/diploi/component-asp/icon.svg?ref=main)**ASP.NET**](/building/components/asp)[![](https://diploi.b-cdn.net/component/diploi/component-astro/icon.svg?ref=main)**Astro**](/building/components/astro)[![](https://diploi.b-cdn.net/component/diploi/component-blazor/icon.svg?ref=main)**Blazor**](/building/components/blazor)[![](https://diploi.b-cdn.net/component/diploi/component-bun/icon.svg?ref=main)**Bun**](/building/components/bun)[![](https://diploi.b-cdn.net/component/diploi/component-deno/icon.svg?ref=main)**Deno**](/building/components/deno)[![](https://diploi.b-cdn.net/component/diploi/component-django/icon.svg?ref=main)**Django**](/building/components/django)[![](https://diploi.b-cdn.net/component/diploi/component-fastapi/icon.svg?ref=main)**FastAPI**](/building/components/fastapi)[![](https://diploi.b-cdn.net/component/diploi/component-flask/icon.svg?ref=main)**Flask**](/building/components/flask)[![](https://diploi.b-cdn.net/component/diploi/component-ghost/icon.svg?ref=main)**Ghost**](/building/components/ghost)[![](https://diploi.b-cdn.net/component/diploi/component-hono/icon.svg?ref=main)**Hono**](/building/components/hono)[![](https://diploi.b-cdn.net/component/diploi/component-laravel/icon.svg?ref=main)**Laravel**](/building/components/laravel)[![](https://diploi.b-cdn.net/component/diploi/component-n8n/icon.svg?ref=main)**n8n**](/building/components/n8n)[![](https://diploi.b-cdn.net/component/diploi/component-nextjs/icon.svg?ref=main)**Next.js**](/building/components/next)[![](https://diploi.b-cdn.net/component/diploi/component-nodejs/icon.svg?ref=main)**Node.js**](/building/components/node)[![](https://diploi.b-cdn.net/component/diploi/component-python/icon.svg?ref=main)**Python**](/building/components/python)[![](https://diploi.b-cdn.net/component/diploi/component-react-vite/icon.svg?ref=main)**React + Vite**](/building/components/react-vite)[![](https://diploi.b-cdn.net/component/diploi/component-static/icon.svg?ref=main)**Static Website**](/building/components/static)[![](https://diploi.b-cdn.net/component/diploi/component-supabase/icon.svg?ref=main)**Supabase**](/building/components/supabase)[![](https://diploi.b-cdn.net/component/diploi/component-sveltekit/icon.svg?ref=main)**SvelteKit**](/building/components/sveltekit)[![](https://diploi.b-cdn.net/component/diploi/component-tanstack-start/icon.svg?ref=main)**TanStack Start**](/building/components/tanstack-start) *** ### 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) [ASP.NET component repository](https://github.com/diploi/component-asp) *** ### Astro A static site builder that lets you write components with a broad selection of frontend frameworks, while optimizing for performance and modern SEO practices. [How to add Astro to a project](/building/components/astro) [Astro component repository](https://github.com/diploi/component-astro) [Tutorial: hosting Astro apps on Diploi](https://diploi.com/blog/hosting_astro_apps) *** ### 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) [Blazor component repository](https://github.com/diploi/component-blazor) *** ### Bun A JavaScript runtime designed to be faster than Node.js, with native bundling, support for TypeScript, and package management support. [How to add Bun to a project](/building/components/bun) [Bun component repository](https://github.com/diploi/component-bun) [Tutorial: hosting Bun apps on Diploi](https://diploi.com/blog/hosting_bun_apps) *** ### Deno A JavaScript and TypeScript runtime for APIs and backend services. [How to add Deno to a project](/building/components/deno) [Deno component repository](https://github.com/diploi/component-deno) [Tutorial: hosting Deno apps on Diploi](https://diploi.com/blog/hosting_deno_apps) *** ### Django A high-level Python web framework for full-stack applications. [How to add Django to a project](/building/components/django) [Django component repository](https://github.com/diploi/component-django) [Django docs](https://docs.djangoproject.com/en/stable/) [Tutorial: hosting Django apps on Diploi](https://diploi.com/blog/hosting_django_apps) *** ### FastAPI A Python framework used to create APIs with automatic documentation. [How to add FastAPI to a project](/building/components/fastapi) [FastAPI component repository](https://github.com/diploi/component-fastapi) [Tutorial: hosting FastAPI apps on Diploi](https://diploi.com/blog/hosting_fastapi_apps) *** ### Flask A minimalist Python framework, designed for lightweight APIs, dashboards, services, and full-stack applications. [How to add Flask to a project](/building/components/flask) [Flask component repository](https://github.com/diploi/component-flask) [Tutorial: hosting Flask apps on Diploi](https://diploi.com/blog/hosting_flask_apps) *** ### Ghost An open-source content management system designed for publishing and managing blogs, online publications or websites. [How to add Ghost to a project](/building/components/ghost) [Ghost component repository](https://github.com/diploi/component-ghost) [Tutorial: hosting a Ghost blog on Diploi](https://diploi.com/blog/hosting_a_ghost_blog) *** ### Hono A small web framework designed to build APIs and backend applications. [How to add Hono to a project](/building/components/hono) [Hono component repository](https://github.com/diploi/component-hono) [Tutorial: hosting Hono apps on Diploi](https://diploi.com/blog/hosting_hono_apps) *** ### Laravel A full-stack PHP framework with native support for modern JS-based frontend frameworks. [How to add Laravel to a project](/building/components/laravel) [Laravel component repository](https://github.com/diploi/component-laravel) [Tutorial: hosting Laravel apps on Diploi](https://diploi.com/blog/hosting_laravel_apps) *** ### n8n A workflow automation platform used to run trigger-driven workloads, using a GUI to set up triggers and workflow logic. [How to add n8n to a project](/building/components/n8n) [n8n component repository](https://github.com/diploi/component-n8n) [Tutorial: hosting n8n on Diploi](https://diploi.com/blog/hosting_n8n) [AI Gateway](/reference/ai-gateway) *** ### Next.js A React-based web development framework for server-side and static web rendering. [How to add Next.js to a project](/building/components/next) [Next.js component repository](https://github.com/diploi/component-nextjs) [Tutorial: hosting Next.js apps on Diploi](https://diploi.com/blog/hosting_nextjs_apps) *** ### Node.js A runtime used to develop backend applications and APIs using JavaScript. [How to add Node.js to a project](/building/components/node) [Node.js component repository](https://github.com/diploi/component-nodejs) [Node.js docs](https://nodejs.org/en/docs) [Tutorial: hosting Node.js apps on Diploi](https://diploi.com/blog/hosting_node_apps) *** ### Python Python [How to add Python to a project](/building/components/python) [Python component repository](https://github.com/diploi/component-python) *** ### 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. [How to add React + Vite to a project](/building/components/react-vite) [React + Vite component repository](https://github.com/diploi/component-react-vite) [Tutorial: hosting React apps on Diploi](https://diploi.com/blog/hosting_react_apps) *** ### Static Website Host static websites with Caddy [How to add Static Website to a project](/building/components/static) [Static Website component repository](https://github.com/diploi/component-static) *** ### Supabase An open-source backend platform that bundles multiple services into one, such as Postgres, storage, auth, real-time listeners, and edge functions. [How to add Supabase to a project](/building/components/supabase) [Supabase component repository](https://github.com/diploi/component-supabase) [Tutorial: hosting Supabase on Diploi](https://diploi.com/blog/hosting_supabase) *** ### SvelteKit A framework for building performant web applications with Svelte, offering server-side rendering. [How to add SvelteKit to a project](/building/components/sveltekit) [SvelteKit component repository](https://github.com/diploi/component-sveltekit) [SvelteKit docs](https://svelte.dev/docs/kit/introduction) [Tutorial: hosting Svelte apps on Diploi](https://diploi.com/blog/hosting_svelte_apps) *** ### TanStack Start One Router-first app, from server request to client navigation [How to add TanStack Start to a project](/building/components/tanstack-start) [TanStack Start component repository](https://github.com/diploi/component-tanstack-start) # Building › Components supported › ASP.NET Source: https://docs.diploi.com/building/components/asp > 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 to your 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-05.2026 ``` Note * If the folder of the component in your repository is not named `asp`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: ASP.NET identifier: asp package: https://github.com/diploi/component-asp#v10.0-05.2026 env: include: - postgres.* ``` ## ASP.NET reference Check a running deployment Run `diploi describe asp` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **ASP.NET**. Here you can also add a frontend framework to create a monorepo app 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository** to generate a new GitHub repo 5. Finally, click **Launch Stack** Link to the full guide - upcoming #### Development During development, the container uses `dotnet watch` to enable automatic reloads when files change. The development server is started with: ```sh dotnet watch --no-launch-profile --hot-reload --non-interactive ``` This will: * Use `dotnet watch` to monitor for changes to C# source files and restart the server when changes are detected. * Run the ASP.NET application with hot reload enabled. * Start the app on port 5103. * Avoid using any launch profile so environment variables are controlled by the container. #### Installing Packages **NuGet packages** (C# libraries and frameworks): ```sh dotnet add package ``` For example: ```sh dotnet add package Newtonsoft.Json dotnet add package Microsoft.EntityFrameworkCore.SqlServer ``` > **Important:** After running `dotnet add package `, always run `dotnet build` to resolve new dependency update. #### Production Builds a production-ready image. During the build, dependencies are restored with `dotnet restore` and the application is published with `dotnet publish`. When the container starts, it runs: ```sh dotnet component-asp.dll ``` This uses the compiled .NET application optimized for production deployment. #### Data Protection The application uses ASP.NET Core Data Protection for securing authentication cookies and anti-forgery tokens. In Kubernetes deployments, data protection keys are persisted using a PersistentVolumeClaim to ensure session continuity across pod restarts. ## See also * [Using Components](/building/components) * [ASP.NET component repository](https://github.com/diploi/component-asp) * [ASP.NET on diploi.com](https://diploi.com/component/asp) * [ASP.NET Core documentation](https://docs.microsoft.com/en-us/aspnet/core/) * [.NET documentation](https://docs.microsoft.com/en-us/dotnet/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Astro Source: https://docs.diploi.com/building/components/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#v7.1.1 ``` Note * If the folder of the component in your repository is not named `astro`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Astro identifier: astro package: https://github.com/diploi/component-astro#v7.1.1 env: include: - postgres.* ``` ## Astro reference Check a running deployment Run `diploi describe astro` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Launch a trial, no registration needed Uses the official [node](https://hub.docker.com/_/node) Docker image. Has the [@astrojs/ node](https://docs.astro.build/en/guides/integrations-guide/node/) adapter preconfigured. ### Operation #### Getting started 1. **Sign up** at `https://console.diploi.com/` using your GitHub account. 2. In your dashboard, click **Create Project +** 3. Under **Pick Components**, choose **Astro**\ If you want to expand your Astro website with other tools, like a backend framework, here you can add them. 4. In **Pick Add-ons**, select any databases or tools supported on Diploi. 5. In **Repository**, choose **Create Repository** which will generate a new GitHub repo for you. 6. Click **Launch Stack** Prefer the full guide? Check #### Package managers Supports **Bun**, **Yarn**, **npm**, and **pnpm**. The package manager is auto-detected from your lockfile (`bun.lock`, `yarn.lock`, `package-lock.json`, or `pnpm-lock.yaml`). The install and build steps always use the detected package manager. #### Development When the component is first initialized, dependencies are installed using the detected package manager. The development server is then started with: ```sh npm run dev -- --host ``` This can be changed with the `containerCommands.developmentStart` field in `diploi.yaml`. #### Production Builds a production-ready image. Dependencies are installed and `npm run build` is run during the image build, using the detected package manager. When the container starts, it runs: ```sh npm start ``` This can be changed with the `containerCommands.productionStart` field in `diploi.yaml`. ##### ENV Since Vite embeds environment variables during the build step, we provide two ways to manage ENV values in production builds: 1. For values that are not deployment-dependent, define them in `diploi.yaml` using the [static import syntax](https://docs.diploi.com/reference/diploi-yaml#env). The values are exposed to the `Dockerfile` as `ARG` variables. 2. For values that depend on a specific deployment (such as variables imported from other components in `diploi.yaml`, or configured in the **Options** tab), enable the **runtime build** option. ##### Runtime Build When runtime build is enabled (which it is by default), `npm run build` is executed again when the container starts. This ensures that environment variables from the running deployment are correctly applied, and that any data loaded from other components can use the internal network. To disable runtime build, set `__VITE_RUNTIME_BUILD` to `false` in `diploi.yaml`: ```yaml - name: Astro identifier: astro package: https://github.com/diploi/component-astro#v1.0.0 env: include: - name: __VITE_RUNTIME_BUILD value: false ``` ## See also * [Using Components](/building/components) * [Astro component repository](https://github.com/diploi/component-astro) * [Astro on diploi.com](https://diploi.com/component/astro) * [Tutorial: hosting Astro apps on Diploi](https://diploi.com/blog/hosting_astro_apps) * [Astro docs](https://docs.astro.build/en/getting-started/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Blazor Source: https://docs.diploi.com/building/components/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-05.2026 ``` Note * If the folder of the component in your repository is not named `blazor`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Blazor identifier: blazor package: https://github.com/diploi/component-blazor#v10.0-05.2026 env: include: - postgres.* ``` ## Blazor reference Check a running deployment Run `diploi describe blazor` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Blazor**. Here you can also add a backend framework to create a monorepo app 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository** to generate a new GitHub repo 5. Finally, click **Launch Stack** Link to the full guide - upcoming #### Development During development, the container uses `dotnet watch` to enable automatic reloads when files change. The development server is started with: ```sh dotnet watch --no-launch-profile --hot-reload --non-interactive ``` This will: * Use `dotnet watch` to monitor for changes to .cs, .razor, and .css files and restart the server when changes are detected. * Run the Blazor Server application with hot reload enabled. * Start the app on port 5054. * Enable automatic browser refresh when Razor components or CSS files change. #### Installing Packages **Front-end libraries** (CSS/JS frameworks like Bootstrap, jQuery, etc.): First, ensure .NET tools are restored: ```sh dotnet tool restore ``` Then install front-end libraries using LibMan: ```sh dotnet tool run libman install @ --provider cdnjs --destination wwwroot/lib/ ``` For example: ```sh dotnet tool run libman install bootstrap@5.3.0 --provider cdnjs --destination wwwroot/lib/bootstrap dotnet tool run libman install jquery@3.7.1 --provider cdnjs --destination wwwroot/lib/jquery ``` **NuGet packages** (C# libraries and frameworks): ```sh dotnet add package ``` For example: ```sh dotnet add package Newtonsoft.Json dotnet add package Microsoft.EntityFrameworkCore.SqlServer ``` The `libman.json` file manages client-side libraries, while the `.csproj` file tracks NuGet dependencies. Both are automatically restored during development and build. > **Important:** Important: After running dotnet add package , always run dotnet build to resolve new dependency update. #### Production Builds a production-ready image. During the build, dependencies are restored with `dotnet restore` and the application is published with `dotnet publish`. When the container starts, it runs: ```sh dotnet component-blazor.dll ``` This uses the compiled .NET application optimized for production deployment. #### Data Protection The application uses ASP.NET Core Data Protection for securing authentication cookies and anti-forgery tokens. In Kubernetes deployments, data protection keys are persisted using a PersistentVolumeClaim to ensure session continuity across pod restarts. ## See also * [Using Components](/building/components) * [Blazor component repository](https://github.com/diploi/component-blazor) * [Blazor on diploi.com](https://diploi.com/component/blazor) * [Blazor documentation](https://docs.microsoft.com/en-us/aspnet/core/blazor/) * [ASP.NET Core documentation](https://docs.microsoft.com/en-us/aspnet/core/) * [.NET documentation](https://docs.microsoft.com/en-us/dotnet/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Bun Source: https://docs.diploi.com/building/components/bun > Deploy Bun apps and tooling with Diploi. Bun is a high-performance JavaScript runtime that includes a bundler, test runner, and package manager. Use this component when you want Bun’s fast startup times and all-in-one tooling for web services or utilities. Diploi handles the deployment so you can take advantage of Bun without custom infrastructure. ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Bun to your project. ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 ``` Note * If the folder of the component in your repository is not named `bun`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 env: include: - postgres.* ``` ## Bun reference Check a running deployment Run `diploi describe bun` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Launch a trial, no card or registration required A generic Bun component that can be used to run any JS / TS app. Uses the official [oven/bun](https://hub.docker.com/r/oven/bun) Docker image. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Bun** You can add other frameworks from this page if you want to create a monorepo application, eg, Bun for API + React for frontend. 3. In **Pick Add-ons**, select any databases you need. 4. Choose **Create Repository**, which will generate a new GitHub repo. 5. Finally, click **Launch Stack** Link the guide #### Development Will run `bun install` when component is first initialized, and `bun dev` when deployment is started. #### Production Will build a production ready image. Image runs `bun install` & `bun run build` when being created. Once the image runs, `bun start` is called. ## See also * [Using Components](/building/components) * [Bun component repository](https://github.com/diploi/component-bun) * [Bun on diploi.com](https://diploi.com/component/bun) * [Tutorial: hosting Bun apps on Diploi](https://diploi.com/blog/hosting_bun_apps) * [Bun documentation](https://bun.sh/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Deno Source: https://docs.diploi.com/building/components/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.7.14 ``` Note * If the folder of the component in your repository is not named `deno`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Deno identifier: deno package: https://github.com/diploi/component-deno#v2.7.14 env: include: - postgres.* ``` ## Deno reference Check a running deployment Run `diploi describe deno` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme A generic Deno component that can be used to run any Deno app. Uses the official [Deno](https://hub.docker.com/r/denoland/deno) Docker image. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Deno** 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository**, which will generate a new GitHub repo 5. Lastly, click **Launch Stack** Link to guide, explains how to add a custom domain and launch to production #### Development Runs `deno task dev` when deployment is started, which executes your app in watch mode with network and environment variable access: ```sh deno run --watch --allow-net --allow-env src/main.ts ``` No `deno install` is required, as new import in TypeScript files will trigger Deno to automatically download and cache those modules as needed. #### Production Builds a production-ready image. Runs `deno task prod` to start your app with network and environment variable access: ```sh deno run --allow-net --allow-env src/main.ts ``` Dependencies are cached during the build stage using `deno cache .`. ## See also * [Using Components](/building/components) * [Deno component repository](https://github.com/diploi/component-deno) * [Deno on diploi.com](https://diploi.com/component/deno) * [Tutorial: hosting Deno apps on Diploi](https://diploi.com/blog/hosting_deno_apps) * [Deno documentation](https://docs.deno.com/runtime/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Django Source: https://docs.diploi.com/building/components/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.7 ``` Note * If the folder of the component in your repository is not named `django`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Django identifier: django package: https://github.com/diploi/component-django#v6.0.7 env: include: - postgres.* ``` ## Django reference What Django defines in a deployment. Check a running deployment Run `diploi describe django` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables Django sets these values in every deployment. Other components can import them with [`env.include`](/reference/diploi-yaml#env) as `django.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Secret Key** Django Secret Key. | Variable | Type | Default | Description | | ------------ | ------ | ----------- | ----------- | | `SECRET_KEY` | secret | *generated* | | ## Readme Start a demo, no card required Getting started guide A generic Django component ready to build your Django app. This component was kickstarted running `django-admin startproject djangoapp` and it has `DEBUG=true` inside **settings.py** by default **To secure your Django app,** you must **update your SECRET\_KEY in settings.py** By default all Django apps use SQlite, which you must update to use your database of choice inside **settings.py** Uses the official [astral-sh/uv:3.13-alpine](https://github.com/astral-sh/uv/pkgs/container/uv) Docker image and Django ##### IMPORTANT * You must generate a new SECRET\_KEY for your own application * Remember to update the database settings inside **settings.py** to match your own database config * In production you must remember to update your **settings.py**, by changing `DEBUG=false` and if you want to use external CDNs for your static files, you will need to update the `STATIC_ROOT` * For production and development, you are free to change the app server runner, so for example, if you prefer `uwsgi` you can change it directly on the Dockerfile for production and development * To install new packages, this component uses `uv`, so you can add new packages using `uv add ` ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Django** 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository**, which will generate a new GitHub repo 5. Now click **Launch Stack** #### Development Will run `uv sync` for pyproject.toml or `uv pip install -r requirements.txt` for requirements.txt when component is first initialized, and `uv run python manage.py runserver 0.0.0.0:8000` when deployment is started. #### Production To get all static files, the image runs the command: `uv run --locked --no-dev python manage.py collectstatic --noinput` to get all static files. Lastly, the image will start the production server with the command: `uv run gunicorn djangoapp.wsgi:application --bind 0.0.0.0:8000 --workers 3 --log-level info` #### Common tasks (using uv) * Create a superuser\ `uv run python manage.py createsuperuser` * Run migrations\ `uv run python manage.py migrate` * Switch the database to Postgres instead of SQLite 1. Install the Postgres driver (already present in `pyproject.toml`, but if missing run `uv add "psycopg2-binary"`). 2. In `djangoapp/settings.py`, set `DATABASES["default"]` to read from `DATABASE_URL` (e.g. using `env.dj_db_url` if `environs[django]` is installed). A typical value:\ `postgres://postgres:postgres@postgres.postgres:5432/app` 3. Export `DATABASE_URL` in your environment (or add to `.env`), then run `uv run python manage.py migrate`. * Adjust CSRF trusted origins\ In `djangoapp/settings.py`, the list comes from `CSRF_TRUSTED_ORIGINS` env var. Add hosts as a comma-separated list, e.g.:\ `export CSRF_TRUSTED_ORIGINS="https://example.com,https://admin.example.com"`\ After updating, restart the app so Django picks up the new origins. ## See also * [Using Components](/building/components) * [Django component repository](https://github.com/diploi/component-django) * [Django on diploi.com](https://diploi.com/component/django) * [Django docs](https://docs.djangoproject.com/en/stable/) * [Tutorial: hosting Django apps on Diploi](https://diploi.com/blog/hosting_django_apps) * [Django for production](https://docs.djangoproject.com/en/5.2/howto/deployment/checklist/) * [Django static files](https://docs.djangoproject.com/en/5.2/howto/static-files/) * [SECRET\_KEY in Django](https://docs.djangoproject.com/en/5.2/ref/settings/#std-setting-SECRET_KEY) * [Databases in Django](https://docs.djangoproject.com/en/5.2/ref/databases/) * [Working with multiple databases in Django](https://docs.djangoproject.com/en/5.2/topics/db/multi-db/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › FastAPI Source: https://docs.diploi.com/building/components/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.136.1 ``` Note * If the folder of the component in your repository is not named `fastapi`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: FastAPI identifier: fastapi package: https://github.com/diploi/component-fastapi#v0.136.1 env: include: - postgres.* ``` ## FastAPI reference Check a running deployment Run `diploi describe fastapi` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **FastAPI**. Here you can also add a frontend framework to create a monorepo app, eg, FastAPI for backend and React+Vite for frontend 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository** to generate a new GitHub repo 5. Finally, click **Launch Stack** Link to the full guide #### Python version The default Python version is **3.12**. You can change it in two ways: * **`PYTHON_VERSION` environment variable** - set this in `diploi.yaml` as a [static ENV](https://docs.diploi.com/reference/diploi-yaml/#static-values) under your component’s environment variables. This controls the version used by both the development and production environments. * **`.python-version` file** - add a `.python-version` file to your component’s folder containing just the version number (e.g. `3.11`). This is the standard convention used by `uv` and other Python tools, and is a good choice if you want the version pinned in your repository. If both are set, the `.python-version` file takes precedence. #### Development The development server is started with: ```sh uv run --with uvicorn uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload --reload-dir src --reload-dir .venv/lib ``` This can be changed with the `containerCommands.developmentStart` field in `diploi.yaml`. #### Production Builds a production-ready image. During the build, dependencies are installed with `uv sync` or `uv pip install`. When the container starts, it runs: ```sh uv run --with uvicorn uvicorn src.main:app --host 0.0.0.0 --port 8000 --proxy-headers ``` This can be changed with the `containerCommands.productionStart` field in `diploi.yaml`. ## See also * [Using Components](/building/components) * [FastAPI component repository](https://github.com/diploi/component-fastapi) * [FastAPI on diploi.com](https://diploi.com/component/fastapi) * [Tutorial: hosting FastAPI apps on Diploi](https://diploi.com/blog/hosting_fastapi_apps) * [FastAPI documentation](https://fastapi.tiangolo.com/) * [Python documentation](https://docs.python.org/) * [uv documentation](https://docs.astral.sh/uv/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Flask Source: https://docs.diploi.com/building/components/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-05.2026 ``` Note * If the folder of the component in your repository is not named `flask`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Flask identifier: flask package: https://github.com/diploi/component-flask#v3.1.3-05.2026 env: include: - postgres.* ``` ## Flask reference Check a running deployment Run `diploi describe flask` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Flask**. Here you can also add a frontend framework to create a monorepo app, eg, Flask for backend and React+Vite for frontend 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository** to generate a new GitHub repo 5. Finally, click **Launch Stack** Full guide at #### Development ```sh uv run flask --app src/main.py run --host=0.0.0.0 --port=8000 --debug ``` This will: * Watch for changes and restart the server automatically * Makes the app available on all network interfaces at port 8000, with debug mode enabled #### Production Builds a production-ready image. During the build, dependencies are installed with `uv sync` or `uv pip install`. When the container starts, it runs: ```sh uv run --frozen gunicorn -w 4 -b 0.0.0.0:8000 src.main:app ``` This uses the Gunicorn to serve your application on port 8000. ## See also * [Using Components](/building/components) * [Flask component repository](https://github.com/diploi/component-flask) * [Flask on diploi.com](https://diploi.com/component/flask) * [Tutorial: hosting Flask apps on Diploi](https://diploi.com/blog/hosting_flask_apps) * [Flask documentation](https://flask.palletsprojects.com/en/stable/) * [Python documentation](https://docs.python.org/) * [uv documentation](https://docs.astral.sh/uv/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Ghost Source: https://docs.diploi.com/building/components/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#v6.36.0 ``` Note * If the folder of the component in your repository is not named `ghost`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Ghost identifier: ghost package: https://github.com/diploi/component-ghost#v6.36.0 env: include: - postgres.* ``` ## Database Ghost stores its content in MariaDB. When you pick Ghost in the Stack Builder, the [MariaDB add-on](/building/add-ons/mariadb) and the environment variable mapping below are added to your project automatically. If you add Ghost to an existing project by editing `diploi.yaml` yourself, add them too: ```yaml components: - name: Ghost identifier: ghost package: https://github.com/diploi/component-ghost#v6.36.0 env: include: - mariadb.MARIADB_HOST:database__connection__host - mariadb.MARIADB_USER:database__connection__user - mariadb.MARIADB_PASSWORD:database__connection__password addons: - name: MariaDB identifier: mariadb package: https://github.com/diploi/addon-mariadb#v1.0.0-url ``` The mapping is needed because Ghost reads its database settings from `database__connection__*` variables. ## Ghost reference What Ghost defines in a deployment. Check a running deployment Run `diploi describe ghost` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables Ghost sets these values in every deployment. Other components can import them with [`env.include`](/reference/diploi-yaml#env) as `ghost.*`. Defaults marked *generated* are unique to each deployment. **Other variables** Set by the package. Override them on the deployment’s **Environment** tab or in `diploi.yaml`. | Variable | Default | | -------------------------------- | --------------------- | | `database__client` | `mysql` | | `database__connection__database` | `ghost` | | `storage__active` | `DiploiImagesStorage` | | `storage__media__adapter` | `DiploiMediaStorage` | | `storage__files__adapter` | `DiploiFilesStorage` | ## Readme Start with a free trial, no account required Run [Ghost](https://ghost.org/) on Diploi. Uses the official [ghost](https://hub.docker.com/_/ghost/) Docker image. ### Operation Includes custom storage adapters for Diploi. These save images, files and media to a storage volume that will persist between reboots. This volume can be found at `/data` on the Ghost `app` container. #### Getting started 1. **Sign up** for Diploi at `https://console.diploi.com/` using your GitHub account. 2. In your dashboard, click **Create Project +** 3. Under **Pick Components**, choose **Ghost**\ If you want to expand your Ghost blog with other tools, like a backend framework to add an API, in this section, you can add them. They will all be hosted on a single server, reducing costs and complexity. 4. In **Pick Add-ons**, select any databases or tools you want to include. 5. In **Repository**, choose **Create Repository** which will generate a new GitHub repo for you. 6. Click **Launch Stack** Check the full guide #### Development When running a development environment, Ghost will be run in development mode too. This will allow you to develop custom themes and plugins with ease. To learn more about developing on Ghost, see the [Developing Themes](https://ghost.org/docs/install/local/#developing-themes) section of their docs. #### Production The production image will be an optimized, minimal version with your custom code baked in. Depending on which features you have been working on, you might have to apply them in the Ghost Admin panel (like themes and plugins). ## See also * [Using Components](/building/components) * [Ghost component repository](https://github.com/diploi/component-ghost) * [Ghost on diploi.com](https://diploi.com/component/ghost) * [Tutorial: hosting a Ghost blog on Diploi](https://diploi.com/blog/hosting_a_ghost_blog) * [Ghost documentation](https://ghost.org/docs/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Hono Source: https://docs.diploi.com/building/components/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.12.19 ``` Note * If the folder of the component in your repository is not named `hono`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Hono identifier: hono package: https://github.com/diploi/component-hono#v4.12.19 env: include: - postgres.* ``` ## Hono reference Check a running deployment Run `diploi describe hono` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Start a free demo without registering an account Run [Hono](https://hono.dev/) on Diploi. Uses [Bun](https://bun.sh/) to handle dependencies and to run the application. Uses the official [oven/bun](https://hub.docker.com/r/oven/bun) Docker image. ### Operation #### Getting started 1. **Sign up** for a free Diploi account at 2. In the Dashboard, click **Create Project +** 3. Under **Pick Components**, choose **Hono** You can add other frameworks from this page. 4. In **Pick Add-ons**, select any databases or extra tools you need. 5. Choose **Create Repository** so Diploi generates a new GitHub repo for your project. 6. Click **Launch Stack** Link to guide #### Development Will run `bun install` when component is first initialized, and `bun dev` when deployment is started. #### Production Will build a production ready image. Image runs `bun install` & `bun run build` when being created. Once the image runs, `bun start` is called. ## See also * [Using Components](/building/components) * [Hono component repository](https://github.com/diploi/component-hono) * [Hono on diploi.com](https://diploi.com/component/hono) * [Tutorial: hosting Hono apps on Diploi](https://diploi.com/blog/hosting_hono_apps) * [Hono documentation](https://hono.dev/docs/) * [Bun documentation](https://bun.sh/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Laravel Source: https://docs.diploi.com/building/components/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-05.2026 ``` Note * If the folder of the component in your repository is not named `laravel`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Laravel identifier: laravel package: https://github.com/diploi/component-laravel#v13-05.2026 env: include: - postgres.* ``` ## Laravel reference What Laravel defines in a deployment. Check a running deployment Run `diploi describe laravel` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables Laravel sets these values in every deployment. Other components can import them with [`env.include`](/reference/diploi-yaml#env) as `laravel.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Laravel Environment Variables** Laravel application environment variables. | Variable | Type | Default | Description | | ---------- | ------ | ----------- | ---------------------------------- | | `APP_NAME` | string | `Laravel` | | | `APP_KEY` | secret | *generated* | Laravel application encryption key | | `APP_URL` | string | *generated* | | ## Readme Launch a trial, no account needed Uses the official [FrankenPHP](https://hub.docker.com/r/dunglas/frankenphp) Docker image. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Laravel (PHP)** You can add other frameworks from this page if you want to create a monorepo application, eg, Laravel + (React + Vite for frontend). 3. In **Pick Add-ons**, select any databases or extra tools you need. 4. Choose **Create Repository** so Diploi generates a new GitHub repo for your project. 5. Click **Launch Stack** Check the guide #### Development Will run `composer install --optimize-autoloader --no-interaction` when component is first initialized, and `frankenphp php-server` when deployment is started. #### Production Will build a production ready image. Image runs `composer install --no-dev --optimize-autoloader --no-interaction` when being created. Once the image runs, `frankenphp php-server` is called. ## See also * [Using Components](/building/components) * [Laravel component repository](https://github.com/diploi/component-laravel) * [Laravel on diploi.com](https://diploi.com/component/laravel) * [Tutorial: hosting Laravel apps on Diploi](https://diploi.com/blog/hosting_laravel_apps) * [Laravel documentation](https://laravel.com/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › n8n Source: https://docs.diploi.com/building/components/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.29.1 ``` Note * If the folder of the component in your repository is not named `n8n`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: n8n identifier: n8n package: https://github.com/diploi/component-n8n#v2.29.1 env: include: - postgres.* ``` ## Database n8n stores its data in PostgreSQL. When you pick n8n in the Stack Builder, the [PostgreSQL add-on](/building/add-ons/postgres) and the environment variable mapping below are added to your project automatically. If you add n8n to an existing project by editing `diploi.yaml` yourself, add them too: ```yaml components: - name: n8n identifier: n8n package: https://github.com/diploi/component-n8n#v2.29.1 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-pgvector ``` The mapping is needed because n8n only reads the variable names listed in [its documentation](https://docs.n8n.io/hosting/configuration/environment-variables/database/#postgresql). ## AI models To use Diploi-hosted models in n8n, create an OpenAI credential that points at the AI Gateway: * **Base URL:** `{diploi-ai-gateway-url}/openai/v1` * **API key:** `{diploi-ai-gateway-token}` Inject those placeholders as env vars on the n8n component, then pick a [supported model](/reference/ai-gateway#supported-models). See [AI Gateway](/reference/ai-gateway). ## n8n reference What n8n defines in a deployment. Check a running deployment Run `diploi describe n8n` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables n8n sets these values in every deployment. Other components can import them with [`env.include`](/reference/diploi-yaml#env) as `n8n.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Connection** Superuser & connection configuration. | Variable | Type | Default | Description | | ------------------------ | ------ | ----------- | ----------- | | `DB_POSTGRESDB_DATABASE` | string | `n8n` | | | `N8N_HOST` | string | *generated* | | **Config** n8n onfiguration variables. | Variable | Type | Default | Description | | -------------------- | ------ | ----------- | ----------- | | `N8N_ENCRYPTION_KEY` | secret | *generated* | | **Other variables** Set by the package. Override them on the deployment’s **Environment** tab or in `diploi.yaml`. | Variable | Default | | ---------------------- | ------------ | | `DB_TYPE` | `postgresdb` | | `DB_POSTGRESDB_SCHEMA` | `public` | | `TZ` | `UTC` | | `N8N_SAMESITE_COOKIE` | `none` | | `N8N_SECURE_COOKIE` | `true` | ## Readme Start a demo, no card required A generic n8n component ready to be used for automating tasks. This component uses latest stable N8N docker version and it uses **PostgreSQL** by default. This component is based on the official [n8n Docker image](https://hub.docker.com/r/n8nio/n8n), ensuring compatibility and stability with the latest **n8n** releases. ### Operation #### Getting started 1. In the Dashboard, click Create Project + 2. Under Pick Components, choose **n8n** 3. In Pick Add-ons, you can add one or multiple databases to your app 4. Choose Create Repository, which will generate a new GitHub repo 5. Lastly, click Launch Stack Link to guide, explains how to add a custom domain and launch to production #### Configure a custom base URL 1. Open the n8n web interface and create a new custom credential. 2. In the DevPod terminal, run the following command to find your Diploi base URL and access token: ```bash printenv | grep DIPLOI ``` 3. Return to n8n and use the retrieved values to configure your custom base URL. For detailed instructions, see the [n8n community guide](https://community.n8n.io/t/custom-ai-provider-in-agent-node-or-custom-base-url/93488?tl=en). > Keep your access token private and do not share it publicly. #### Development and Production For development and production, the component’s image is built using the official n8n stable release, ensuring reliability and optimal performance in deployment environments. ##### IMPORTANT * If you want to create your own custom nodes, you can follow n8n’s official documentation ## See also * [Using Components](/building/components) * [n8n component repository](https://github.com/diploi/component-n8n) * [n8n on diploi.com](https://diploi.com/component/n8n) * [Tutorial: hosting n8n on Diploi](https://diploi.com/blog/hosting_n8n) * [AI Gateway](/reference/ai-gateway) * [n8n docs](https://docs.n8n.io/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Next.js Source: https://docs.diploi.com/building/components/next > 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.3.3 ``` Note * If the folder of the component in your repository is not named `next`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Next.js identifier: next package: https://github.com/diploi/component-nextjs#v16.3.3 env: include: - postgres.* ``` ## Next.js reference Check a running deployment Run `diploi describe next` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Launch a trial, no account needed Uses the official [node](https://hub.docker.com/_/node) Docker image. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Next.js** You can add other frameworks from this page if you want to create a monorepo application, eg, Next.js + Bun for backend. 3. In **Pick Add-ons**, select any databases or extra tools you need. 4. Choose **Create Repository** so Diploi generates a new GitHub repo for your project. 5. Click **Launch Stack** Check the guide #### Development Will run `npm install` when component is first initialized, and `npm run dev` when deployment is started. #### Production Will build a production ready image. Image runs `npm install` & `npm build` when being created. Once the image runs, `npm start` is called. ## See also * [Using Components](/building/components) * [Next.js component repository](https://github.com/diploi/component-nextjs) * [Next.js on diploi.com](https://diploi.com/component/next) * [Tutorial: hosting Next.js apps on Diploi](https://diploi.com/blog/hosting_nextjs_apps) * [Next.js documentation](https://nextjs.org/docs) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Node.js Source: https://docs.diploi.com/building/components/node > 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.14.0 ``` Note * If the folder of the component in your repository is not named `node`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Node.js identifier: node package: https://github.com/diploi/component-nodejs#v24.14.0 env: include: - postgres.* ``` ## Node.js reference Check a running deployment Run `diploi describe node` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Start a demo environment (No card or registration needed) A generic Node.js component that can be used to run any Node.js app. Uses the official [node](https://hub.docker.com/_/node) Docker image. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Node.js** 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository**, which will generate a new GitHub repo 5. Lastly, click **Launch Stack** Link to guide (includes additional information) #### Development Will run `npm install` when component is first initialized, and `npm run dev` when deployment is started. #### Production Will build a production ready image. Image runs `npm install` & `npm build` when being created. Once the image runs, `npm start` is called. #### Notes * If you are using packages that use native libraries (like `node-canvas` e.g.), it is a good idea to switch the `Dockerfile` and `Dockerfile.dev` to use `node:XX` instead of `node:XX-slim`. You can also add any missing libraries with `RUN apt update && apt install -y ` in the dockerfiles. ## See also * [Using Components](/building/components) * [Node.js component repository](https://github.com/diploi/component-nodejs) * [Node.js on diploi.com](https://diploi.com/component/node) * [Node.js docs](https://nodejs.org/en/docs) * [Tutorial: hosting Node.js apps on Diploi](https://diploi.com/blog/hosting_node_apps) * [Node official page](https://nodejs.org/en) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Python Source: https://docs.diploi.com/building/components/python > Python ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Python to your project. ```yaml components: - name: Python identifier: python package: https://github.com/diploi/component-python#v05.2026 ``` Note * If the folder of the component in your repository is not named `python`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Python identifier: python package: https://github.com/diploi/component-python#v05.2026 env: include: - postgres.* ``` ## Python reference Check a running deployment Run `diploi describe python` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Python**. Here you can also add a frontend framework to create a monorepo app, eg, Python for backend and React+Vite for frontend 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository** to generate a new GitHub repo 5. Finally, click **Launch Stack** #### Development During development, the container installs `watchfiles` to enable automatic reloads when files change. The development server is started with: ```sh uv run watchfiles "python src/main.py" ``` This will: * Use `watchfiles` to watch for file changes and restart the server automatically. * Run `src/main.py` in an isolated Python environment managed by `uv`. * Automatically detect whether to use `pyproject.toml` or `requirements.txt` for dependency resolution. #### Production Builds a production-ready image. During the build, dependencies are installed with `uv sync` or `uv pip install`. When the container starts, it runs: ```sh uv run --frozen src/main.py ``` This starts your Python application using the exact dependency versions locked in the project. ## See also * [Using Components](/building/components) * [Python component repository](https://github.com/diploi/component-python) * [Python on diploi.com](https://diploi.com/component/python) * [Python documentation](https://docs.python.org/) * [uv documentation](https://docs.astral.sh/uv/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › React + Vite Source: https://docs.diploi.com/building/components/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.8 ``` Note * If the folder of the component in your repository is not named `react-vite`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: React + Vite identifier: react-vite package: https://github.com/diploi/component-react-vite#v19.2.8 env: include: - postgres.* ``` ## React + Vite reference Check a running deployment Run `diploi describe react-vite` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Want to start a quick demo? Use this link No account required This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **React + Vite**. Here you can also add a backend framework to create a monorepo app, eg, React+Vite for frontend and Hono for backend 3. In **Pick Add-ons**, you can add one or multiple databases to your app 4. Choose **Create Repository** to generate a new GitHub repo 5. Finally, click **Launch Stack** For more details, check #### Development Will run `npm install` when component is first initialized, and `npm run dev` when deployment is started. #### Production Builds a production-ready image. The image runs `npm install` and `npm run build` in a GitHub Action during creation. The generated `/dist` folder is served as a static site using [serve](https://github.com/vercel/serve). ##### ENV Since Vite embeds environment variables during the build step, we provide two ways to manage ENV values in production builds: 1. For values that are not deployment-dependent, define them in `diploi.yaml` using the [static import syntax](https://docs.diploi.com/reference/diploi-yaml#env). The values are exposed to the `Dockerfile` as `ARG` variables. 2. For values that depend on a specific deployment (such as variables imported from other components in `diploi.yaml`, or configured in the **Options** tab), enable the **runtime build** option. ##### Runtime Build When runtime build is enabled (which it is by default), `npm run build` is executed again when the container starts. This ensures that environment variables from the running deployment are correctly applied, and that any data loaded from other components can use the internal network. To disable runtime build, set `__VITE_RUNTIME_BUILD` to `false` in `diploi.yaml`: ```yaml - name: React + Vite identifier: react-vite package: https://github.com/diploi/component-react-vite#v19.2.10 env: include: - name: __VITE_RUNTIME_BUILD value: false ``` ## See also * [Using Components](/building/components) * [React + Vite component repository](https://github.com/diploi/component-react-vite) * [React + Vite on diploi.com](https://diploi.com/component/react-vite) * [Tutorial: hosting React apps on Diploi](https://diploi.com/blog/hosting_react_apps) * [React documentation](https://react.dev/) * [Vite documentation](https://vite.dev/) * [serve documentation](https://github.com/vercel/serve) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Static Website Source: https://docs.diploi.com/building/components/static > Host static websites with Caddy ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add Static Website to your project. ```yaml components: - name: Static Website identifier: static package: https://github.com/diploi/component-static#v2 ``` Note * If the folder of the component in your repository is not named `static`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Static Website identifier: static package: https://github.com/diploi/component-static#v2 env: include: - postgres.* ``` ## Static Website reference Check a running deployment Run `diploi describe static` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme A component for hosting static websites on Diploi. Drop in your HTML, CSS, and JavaScript files and get a production-ready, gzip-compressed site served over HTTPS. Uses the official [Caddy](https://hub.docker.com/_/caddy) Docker image. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **Static** 3. Choose **Create Repository**, which will generate a new GitHub repo 4. Click **Launch Stack** #### Development The component serves files directly from your repository root. Edit your HTML, CSS, and JavaScript files and the changes are reflected immediately after a refresh. #### Production Builds a production-ready image containing your static files. Caddy serves them with gzip compression. #### Configuration The component includes a `Caddyfile` that you can freely edit to configure Caddy. You can easily add redirects, custom headers, or URL rewriting rules, for example. ## See also * [Using Components](/building/components) * [Static Website component repository](https://github.com/diploi/component-static) * [Static Website on diploi.com](https://diploi.com/component/static) * [Caddy documentation](https://caddyserver.com/docs/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › Supabase Source: https://docs.diploi.com/building/components/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-patch.1 ``` Note * If the folder of the component in your repository is not named `supabase`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Supabase identifier: supabase package: https://github.com/diploi/component-supabase#v2026.02-patch.1 env: include: - postgres.* ``` ## Supabase reference What Supabase defines in a deployment. Check a running deployment Run `diploi describe supabase` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables Supabase sets these values in every deployment. Other components can import them with [`env.include`](/reference/diploi-yaml#env) as `supabase.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Dashboard** Supabase dashboard configuration. | Variable | Type | Default | Description | | ----------------------------- | ------ | ---------------------- | -------------------- | | `DASHBOARD_USERNAME` | string | `supabase` | Username | | `DASHBOARD_PASSWORD` | secret | *generated* | Password | | `STUDIO_DEFAULT_ORGANIZATION` | string | `Default Organization` | Default Organization | | `STUDIO_DEFAULT_PROJECT` | string | `Default Project` | Default Project | **Custom SMTP Settings** Configure custom SMTP settings to send emails. Optional, off by default. | Variable | Type | Default | Description | | -------------------------- | ------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `SMTP_ADMIN_EMAIL` | string | `admin@example.com` | | | `SMTP_HOST` | string | `core.diploi` | An SMTP server (core.diploi) is available within your deployment, see | | `SMTP_PORT` | integer | `2525` | | | `SMTP_USER` | string | | | | `SMTP_PASS` | string | | | | `SMTP_SENDER_NAME` | string | | | | `ENABLE_EMAIL_SIGNUP` | boolean | `true` | | | `ENABLE_EMAIL_AUTOCONFIRM` | boolean | `false` | Enable Email Automatic Confirmation | **API Keys & Values** Secure keys & values for accessing and running your Supabase services. | Variable | Type | Default | Description | | ------------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------- | | `JWT_SECRET` | secret | *generated* | | | `ANON_KEY` | string | *generated* | | | `SERVICE_ROLE_KEY` | secret | *generated* | To generate new JWT values, see | | `VAULT_ENC_KEY` | secret | *generated* | Vault Encryption Key | | `POOLER_TENANT_ID` | secret | *generated* | | | `LOGFLARE_PUBLIC_ACCESS_TOKEN` | string | *generated* | | | `LOGFLARE_PRIVATE_ACCESS_TOKEN` | secret | *generated* | | | `SECRET_KEY_BASE` | secret | *generated* | Phoenix Secret | **PostgreSQL** Superuser & connection configuration. | Variable | Type | Default | Description | | ------------------- | ------- | ----------- | -------------- | | `POSTGRES_HOST` | string | *generated* | Host | | `POSTGRES_PORT` | integer | `5432` | Port | | `POSTGRES_USER` | string | `postgres` | User | | `POSTGRES_PASSWORD` | secret | *generated* | Password | | `POSTGRES_DB` | string | `postgres` | Database | | `POSTGRES_URL` | string | *generated* | Connection URL | **OpenAI** Add your OpenAI API key to enable SQL Editor Assistant. Optional, off by default. | Variable | Type | Default | Description | | ---------------- | ------ | ------- | ----------- | | `OPENAI_API_KEY` | secret | | | **Google Cloud Project** Support Sign in with Google by connecting to a Google Cloud Platform project. Optional, off by default. | Variable | Type | Default | Description | | ----------------------- | ------ | ------- | --------------------------- | | `GOOGLE_PROJECT_ID` | string | | Google Cloud Project ID | | `GOOGLE_PROJECT_NUMBER` | string | | Google Cloud Project Number | **Internal Addresses** Internal endpoints for different Supabase services. | Variable | Type | Default | Description | | ------------------------ | ------ | ----------- | ----------- | | `AUTH_INTERNAL_URL` | string | *generated* | Auth | | `REST_INTERNAL_URL` | string | *generated* | REST | | `REALTIME_INTERNAL_URL` | string | *generated* | Realtime | | `STORAGE_INTERNAL_URL` | string | *generated* | Storage | | `FUNCTIONS_INTERNAL_URL` | string | *generated* | Functions | | `ANALYTICS_INTERNAL_URL` | string | *generated* | Analytics | | `META_INTERNAL_URL` | string | *generated* | Meta | | `STUDIO_INTERNAL_URL` | string | *generated* | Studio | | `KONG_INTERNAL_URL` | string | *generated* | Kong | **Other variables** Set by the package. Override them on the deployment’s **Environment** tab or in `diploi.yaml`. | Variable | Default | | -------------------------- | ----------------------- | | `SITE_URL` | | | `DISABLE_SIGNUP` | `false` | | `ENABLE_ANONYMOUS_USERS` | `false` | | `ENABLE_PHONE_SIGNUP` | `true` | | `ENABLE_PHONE_AUTOCONFIRM` | `true` | | `FUNCTIONS_VERIFY_JWT` | `false` | | `JWT_EXPIRY` | `3600` | | `PGRST_DB_SCHEMAS` | `public,graphql_public` | | `REALTIME_TENANT_NAME` | `realtime` | | `ADDITIONAL_REDIRECT_URLS` | | ## Readme Run [Supabase](https://supabase.com/) on Diploi. Based on the official [supabase/docker](https://github.com/supabase/supabase/tree/master/docker) `docker-compose.yml` file. ### Operation A full Supabase self-hosted implementation. #### Limitations We know of a few limitations that currently exist with Supabase on Diploi. We are actively working on fixes. * Connection URI’s displayed on Supabase Studio are wrong, please use the ones on Diploi Console #### Authentication Self-hosted Supabase comes with a simple basic auth implementation by default. Diploi implements custom authentication for the admin panel, making it easier to use. You can authenticate with a single-click from Diploi Console, or use username & password to login. You can find the admin credentials from a deployments “Options” tab in the Diploi Console. #### Development ##### Functions You can develop custom functions with [Deno](https://deno.com/). Diploi automatically creates a `/functions` directory for you with a preconfigured `main` function and an example `hello` function. ##### Migrations Database migrations and seeding are supported. Diploi automatically creates a `/migrations` directory and a `seed.sql` file for you. They work with the Supabase CLI to manage schema changes and database seeding in a repeatable way. If the component folder is not named `supabase`, Diploi creates a `supabase` symlink inside it so the Supabase CLI works as expected. For guidance and best practices, see the [official Supabase docs on database migrations](https://supabase.com/docs/guides/deployment/database-migrations). Important Migrations are run automatically in **staging** and **production** deployments. In **development**, use the Supabase CLI to create and run migrations. Important If your Supabase component is located in a folder named `supabase`, you can run CLI commands directly from the `/app` directory. Otherwise, navigate to the component’s folder before running any CLI commands. ## See also * [Using Components](/building/components) * [Supabase component repository](https://github.com/diploi/component-supabase) * [Supabase on diploi.com](https://diploi.com/component/supabase) * [Tutorial: hosting Supabase on Diploi](https://diploi.com/blog/hosting_supabase) * [Supabase documentation](https://supabase.com/docs) * [Self-Hosting Supabase with Docker](https://supabase.com/docs/guides/self-hosting/docker) * [Generate Supabase API keys](https://supabase.com/docs/guides/self-hosting/docker#generate-api-keys) * [Migrations with Supabase CLI](https://supabase.com/docs/guides/deployment/database-migrations) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › SvelteKit Source: https://docs.diploi.com/building/components/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.69.3 ``` Note * If the folder of the component in your repository is not named `sveltekit`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: SvelteKit identifier: sveltekit package: https://github.com/diploi/component-sveltekit#v2.69.3 env: include: - postgres.* ``` ## SvelteKit reference Check a running deployment Run `diploi describe sveltekit` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Launch a demo for free Uses the official [node](https://hub.docker.com/_/node) Docker image. Has the [@sveltejs/adapter-node](https://svelte.dev/docs/kit/adapter-node) adapter preconfigured. ### Operation #### Getting started * Create an account on Diploi, it’s free * Once you are in the Dashboard, click on “Create Project +” * Now you need to select the stack for your app. In the “Pick Components” section, select **SvelteKit**. You can add other frameworks to work along with your SvelteKit app. This also applies to the “Pick Add-ons” section, where you can choose the database for your app. * Next, you need to choose “Create Repository” so your new app will start with a fresh repository. * Finally, click “Launch Stack”. Check the full guide #### Development Will run `npm install` when component is first initialized, and `npm run dev` when deployment is started. #### Production Will build a production ready image. Image runs `npm install` & `npm build` when being created. Once the image runs, `npm start` is called. ## See also * [Using Components](/building/components) * [SvelteKit component repository](https://github.com/diploi/component-sveltekit) * [SvelteKit on diploi.com](https://diploi.com/component/sveltekit) * [SvelteKit docs](https://svelte.dev/docs/kit/introduction) * [Tutorial: hosting Svelte apps on Diploi](https://diploi.com/blog/hosting_svelte_apps) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Components supported › TanStack Start Source: https://docs.diploi.com/building/components/tanstack-start > One Router-first app, from server request to client navigation ## Add to your project Paste this entry into the `components` list in `diploi.yaml` to add TanStack Start to your project. ```yaml components: - name: TanStack Start identifier: tanstack-start package: https://github.com/diploi/component-tanstack-start#main ``` Note * If the folder of the component in your repository is not named `tanstack-start`, add a `folder` parameter with the name of the folder. * Import the environment variables of add-ons, such as a database, into the component with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: TanStack Start identifier: tanstack-start package: https://github.com/diploi/component-tanstack-start#main env: include: - postgres.* ``` ## TanStack Start reference Check a running deployment Run `diploi describe tanstack-start` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ## Readme Launch a trial, no account needed This template provides a minimal setup to get TanStack Start working in Diploi. Uses the official [node](https://hub.docker.com/_/node) Docker image. Server-side rendering is handled by [Nitro](https://nitro.build/), preconfigured through the TanStack Start Vite plugin. ### Operation #### Getting started 1. In the Dashboard, click **Create Project +** 2. Under **Pick Components**, choose **TanStack Start** You can add other frameworks from this page if you want to build a monorepo application, eg, TanStack Start for the frontend and Hono for the backend. 3. In **Pick Add-ons**, select any databases or extra tools you need. 4. Choose **Create Repository** so Diploi generates a new GitHub repo for your project. 5. Click **Launch Stack** #### Package managers Supports **Bun**, **Yarn**, **npm**, and **pnpm**. The package manager is auto-detected from your lockfile (`bun.lock`, `yarn.lock`, `package-lock.json`, or `pnpm-lock.yaml`). The install and build steps always use the detected package manager. #### Development When the component is first initialized, dependencies are installed using the detected package manager. The development server is then started with: ```sh npm run dev -- --host ``` This can be changed with the `containerCommands.developmentStart` field in `diploi.yaml`. #### Production Builds a production ready image. Image runs `npm install` & `npm run build` when being created, using the detected package manager. Once the image runs, `npm start` is called, which serves the Nitro build from `.output/`. This can be changed with the `containerCommands.productionStart` field in `diploi.yaml`. ##### ENV Since Vite replaces environment variables during the build step, the client side code cannot directly access dynamic ENVs in production. You have a few ways to get around this limitation: 1. For values that are not deployment-dependent, define them in `diploi.yaml` using the [static import syntax](https://docs.diploi.com/reference/diploi-yaml#env). The values are exposed to the `Dockerfile` as `ARG` variables. 2. For values that depend on a specific deployment (such as variables imported from other components in `diploi.yaml`, or configured in the **Environment** tab), use the [recommended way to use runtime ENVs in production](https://tanstack.com/start/latest/docs/framework/react/guide/environment-variables#runtime-client-environment-variables-in-production) for TanStack Start. ##### Ports The component serves on port **5173** in both development and production. If you change it, update all of these so they stay in sync: * `hosts[].port` in `diploi.yaml` * `EXPOSE` and `ENV PORT` in `Dockerfile` and `Dockerfile.dev` * `server.port` in `vite.config.ts` — Vite does not read `PORT` from the environment on its own ## See also * [Using Components](/building/components) * [TanStack Start component repository](https://github.com/diploi/component-tanstack-start) * [TanStack Start on diploi.com](https://diploi.com/component/tanstack-start) * [TanStack Start documentation](https://tanstack.com/start/latest) * [React documentation](https://react.dev/) * [Vite documentation](https://vite.dev/) * [Nitro documentation](https://nitro.build/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Using Add-ons Source: https://docs.diploi.com/building/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 [![](https://diploi.b-cdn.net/component/diploi/addon-mariadb/icon.svg?ref=main)**MariaDB**](/building/add-ons/mariadb)[![](https://diploi.b-cdn.net/component/diploi/addon-minio/icon.svg?ref=main)**MinIO**](/building/add-ons/minio)[![](https://diploi.b-cdn.net/component/diploi/addon-mongo/icon.svg?ref=main)**MongoDB**](/building/add-ons/mongo)[![](https://diploi.b-cdn.net/component/diploi/addon-postgres/icon.svg?ref=main)**PostgreSQL**](/building/add-ons/postgres)[![](https://diploi.b-cdn.net/component/diploi/addon-redis/icon.svg?ref=main)**Redis**](/building/add-ons/redis) Note Services are not exposed publicly by default. They can only be accessed by the components in your project. *** ### 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) [MariaDB add-on repository](https://github.com/diploi/addon-mariadb) *** ### 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) [MinIO add-on repository](https://github.com/diploi/addon-minio) *** ### MongoDB A NoSQL document database that stores data in JSON-like documents. [How to add MongoDB to a project](/building/add-ons/mongo) [MongoDB add-on repository](https://github.com/diploi/addon-mongo) *** ### 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) [PostgreSQL add-on repository](https://github.com/diploi/addon-postgres) *** ### 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) [Redis add-on repository](https://github.com/diploi/addon-redis) # Building › Add-ons supported › MariaDB Source: https://docs.diploi.com/building/add-ons/mariadb > Provision MariaDB when your Diploi app needs MySQL compatibility. MariaDB is a relational database that’s compatible with MySQL, and adds performance and tooling improvements. You can use MariaDB when your project requires a db compatible with MySQL or if you are migrating existing MySQL workloads. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add MariaDB to your project. ```yaml addons: - name: MariaDB identifier: mariadb package: https://github.com/diploi/addon-mariadb#v1.0.0-url ``` Note * Components can import the environment variables of this add-on with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 env: include: - mariadb.* ``` ## MariaDB reference What MariaDB defines in a deployment. Check a running deployment Run `diploi describe mariadb` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables MariaDB sets these values in every deployment. Components can import them with [`env.include`](/reference/diploi-yaml#env) as `mariadb.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Connection** Connection & user configuration. | Variable | Type | Default | Description | | ------------------ | ------- | ----------- | ----------- | | `MARIADB_HOST` | string | *generated* | Host | | `MARIADB_PORT` | integer | `3306` | Port | | `MARIADB_USER` | string | `root` | User | | `MARIADB_PASSWORD` | secret | `root` | Password | | `MARIADB_DATABASE` | string | `app` | Database | | `DATABASE_URL` | string | *generated* | | **Other variables** Set by the package. Override them on the deployment’s **Environment** tab or in `diploi.yaml`. | Variable | Default | | -------------- | ------- | | `MARIADB_USER` | `root` | ## Readme Uses the official [mariadb](https://hub.docker.com/_/mariadb) Docker image. ## See also * [Using Add-ons](/building/add-ons) * [MariaDB add-on repository](https://github.com/diploi/addon-mariadb) * [MariaDB docs](https://mariadb.org/documentation/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Add-ons supported › MinIO Source: https://docs.diploi.com/building/add-ons/minio > Provision MinIO as an S3-compatible Diploi add-on. MinIO is an open-source, S3-compatible, object storage system that you can run in Diploi. Use this add-on when your components need to store uploads, backups, or other binary data without relying on an external cloud bucket. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add MinIO to your project. ```yaml addons: - name: MinIO identifier: minio package: https://github.com/diploi/addon-minio#2025-06-13T11-33-47Z ``` Note * Components can import the environment variables of this add-on with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 env: include: - minio.* ``` ## MinIO reference What MinIO defines in a deployment. Check a running deployment Run `diploi describe minio` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables MinIO sets these values in every deployment. Components can import them with [`env.include`](/reference/diploi-yaml#env) as `minio.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Connection** Root user & connection configuration. | Variable | Type | Default | Description | | ----------------------- | ------ | ------------ | ------------- | | `MINIO_HOST` | string | *generated* | Host | | `MINIO_ROOT_USER` | string | `minioadmin` | Root User | | `MINIO_ROOT_PASSWORD` | secret | `minioadmin` | Root Password | | `MINIO_API_ROOT_ACCESS` | string | `on` | Root Access | ## Readme Uses the official [minio/minio](https://hub.docker.com/r/minio/minio) Docker image. ## 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) # Building › Add-ons supported › MongoDB Source: https://docs.diploi.com/building/add-ons/mongo > Attach a MongoDB database to Diploi components. MongoDB 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 MongoDB to your project. ```yaml addons: - name: MongoDB identifier: mongo package: https://github.com/diploi/addon-mongo#v8.2.3-url ``` Note * Components can import the environment variables of this add-on with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 env: include: - mongo.* ``` ## MongoDB reference What MongoDB defines in a deployment. Check a running deployment Run `diploi describe mongo` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables MongoDB sets these values in every deployment. Components can import them with [`env.include`](/reference/diploi-yaml#env) as `mongo.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Connection** Connection configuration. | Variable | Type | Default | Description | | -------------- | ------ | ----------- | ----------- | | `DATABASE_URL` | string | *generated* | | ## Readme Uses the official [mongo](https://hub.docker.com/_/mongo) Docker image. ## See also * [Using Add-ons](/building/add-ons) * [MongoDB add-on repository](https://github.com/diploi/addon-mongo) * [Mongo docs](https://www.mongodb.com/docs/manual/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Add-ons supported › PostgreSQL Source: https://docs.diploi.com/building/add-ons/postgres > 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-pgvector ``` Note * Components can import the environment variables of this add-on with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 env: include: - postgres.* ``` ## PostgreSQL reference What PostgreSQL defines in a deployment. Check a running deployment Run `diploi describe postgres` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables PostgreSQL sets these values in every deployment. Components can import them with [`env.include`](/reference/diploi-yaml#env) as `postgres.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Connection** Superuser & connection configuration. | Variable | Type | Default | Description | | ------------------- | ------- | ----------- | ----------- | | `POSTGRES_HOST` | string | *generated* | Host | | `POSTGRES_PORT` | integer | `5432` | Port | | `POSTGRES_USER` | string | `postgres` | User | | `POSTGRES_PASSWORD` | secret | `postgres` | Password | | `POSTGRES_DB` | string | `app` | Database | | `DATABASE_URL` | string | *generated* | | ## Readme Built on the official [postgres](https://hub.docker.com/_/postgres) Docker image, with third-party extensions installed in [`Dockerfile`](https://github.com/diploi/addon-postgres/blob/main/Dockerfile). ### Extensions Extensions are per-database, so enable the ones you need against your own database: ```sql CREATE EXTENSION IF NOT EXISTS vector; -- pgvector CREATE EXTENSION IF NOT EXISTS pg_stat_statements; -- preloaded, ready to enable ``` Everything else below is part of the [contrib](https://www.postgresql.org/docs/current/contrib.html) set that ships with the base image, so it needs no installation — just `CREATE EXTENSION`: | Extension | Use | | ------------------------------------------ | --------------------------------------------------------------------------------------- | | `pg_trgm` | Fuzzy matching; accelerates `ILIKE` and similarity search | | `btree_gin`, `btree_gist` | Mixed-column GIN indexes and exclusion constraints; commonly needed alongside `pg_trgm` | | `unaccent` | Accent-insensitive search | | `citext` | Case-insensitive text, for emails and usernames | | `pgcrypto` | Hashing and encryption functions | | `postgres_fdw`, `dblink` | Cross-database queries | | `pg_buffercache`, `pgstattuple`, `amcheck` | Diagnostics and corruption checking | `uuid-ossp` and `hstore` are available but not recommended for new schemas — `gen_random_uuid()` and `uuidv7()` are built in, and `jsonb` supersedes `hstore`. #### Adding another extension Add the package to [`Dockerfile`](https://github.com/diploi/addon-postgres/blob/main/Dockerfile) and open a PR. The image is built and published by [`.github/workflows/Prebuild.yaml`](https://github.com/diploi/addon-postgres/blob/main/.github/workflows/Prebuild.yaml). Extensions requiring `shared_preload_libraries` must also be added to the `args` list in [`.diploi/helm/postgres.yaml`](https://github.com/diploi/addon-postgres/blob/main/.diploi/helm/postgres.yaml), where `pg_stat_statements` is already preloaded. Treat additions as permanent. Once a deployment runs `CREATE EXTENSION`, removing that extension from the image breaks the database on its next restart, and dropping an entry from `shared_preload_libraries` stops the cluster from starting at all. Extensions are deliberately not user-configurable at deploy time: an arbitrary image reference would let a deployment run a mismatched PostgreSQL major against an existing data directory, which is unrecoverable without a dump and restore. ### Upgrading PostgreSQL majors Bumping the `FROM` tag in [`Dockerfile`](https://github.com/diploi/addon-postgres/blob/main/Dockerfile) changes the major version. PostgreSQL cannot start on a data directory written by a different major, and storage here is persistent, so a major bump requires `pg_dumpall` on the old version followed by a restore into a freshly initialised directory. Downgrades are not possible in place. ## See also * [Using Add-ons](/building/add-ons) * [PostgreSQL add-on repository](https://github.com/diploi/addon-postgres) * [Postgres docs](https://www.postgresql.org/docs/) * [pgvector](https://github.com/pgvector/pgvector) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Add-ons supported › Redis Source: https://docs.diploi.com/building/add-ons/redis > Add Redis for caching, queues, and ephemeral data in Diploi. Redis is an in-memory data store ideal for caching, rate limiting, queues, and other latency-sensitive workloads. Choose this add-on when your components need fast key-value access or pub/sub messaging. ## Add to your project Paste this entry into the `addons` list in `diploi.yaml` to add Redis to your project. ```yaml addons: - name: Redis identifier: redis package: https://github.com/diploi/addon-redis#v7.4-url ``` Note * Components can import the environment variables of this add-on with [`env.include`](/reference/diploi-yaml#env) in `diploi.yaml`: ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#v1.3.8 env: include: - redis.* ``` ## Redis reference What Redis defines in a deployment. Check a running deployment Run `diploi describe redis` in a development environment to see the values a deployment actually uses, its addresses and its connection strings. Secrets are masked unless you add `--reveal`. Add `--json` to get the same output as JSON, for scripts and AI agents. ### Environment variables Redis sets these values in every deployment. Components can import them with [`env.include`](/reference/diploi-yaml#env) as `redis.*`. Defaults marked *generated* are unique to each deployment. Parameters are set on the deployment’s **Setup** tab. **Persistent Storage** Keep a snapshot of the DB on the disk. Optional, off by default. | Variable | Type | Default | Description | | --------------------- | ------- | ----------- | ------------------------ | | `REDIS_SAVE_INTERVAL` | integer | `60` | Save Interval in Seconds | | `REDIS_URL` | string | *generated* | | ## Readme Uses the official [redis](https://hub.docker.com/_/redis) Docker image. ## 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) # Building › Using Starter Kits Source: https://docs.diploi.com/building/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 [![](https://diploi.b-cdn.net/component/diploi/starter-openclaw/icon.svg?ref=main)**OpenClaw Assistant**](/building/starter-kits/openclaw)[![](https://diploi.b-cdn.net/component/diploi/starter-chat/icon.svg?ref=main)**Chat App**](/building/starter-kits/chat)[![](https://diploi.b-cdn.net/component/diploi/starter-refine-pixels/icon.svg?ref=main)**Collaborative Drawing App**](/building/starter-kits/refine-pixels)[![](https://diploi.b-cdn.net/component/diploi/starter-web-app/icon.svg?ref=main)**Web App**](/building/starter-kits/web-app) Note Starter Kits are different from the Stack Builder. The Stack Builder scaffolds a new project from individual [components](/building/components) and [add-ons](/building/add-ons). Starter Kits provide a complete, working application you can build on. You can extend all Starter Kits available with additional components and add-ons. *** ### OpenClaw Assistant 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 Assistant](https://diploi.com/starter-kit/openclaw) [How to use the OpenClaw Assistant starter kit](/building/starter-kits/openclaw) [OpenClaw Assistant starter kit repository](https://github.com/diploi/starter-openclaw) [OpenClaw GitHub](https://github.com/openclaw/openclaw) [AI Gateway](/reference/ai-gateway) *** ### 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) [Chat App starter kit repository](https://github.com/diploi/starter-chat) [Next.js component](/building/components/next) [Supabase component](/building/components/supabase) [Official Next.js documentation](https://nextjs.org/docs) [Official Supabase documentation](https://supabase.com/docs) *** ### Collaborative Drawing App A fun, collaborative pixel art drawing application built with Refine and Supabase. [Launch Collaborative Drawing App](https://diploi.com/starter-kit/refine-pixels) [How to use the Collaborative Drawing App starter kit](/building/starter-kits/refine-pixels) [Collaborative Drawing App starter kit repository](https://github.com/diploi/starter-refine-pixels) [React + Vite component](/building/components/react-vite) [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/) *** ### 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) [Web App starter kit repository](https://github.com/diploi/starter-web-app) [React + Vite component](/building/components/react-vite) [Supabase component](/building/components/supabase) [Official React documentation](https://react.dev) [Official React Router documentation](https://reactrouter.com) [Official TailwindCSS documentation](https://tailwindcss.com/docs) *** ## 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) # Building › Starter Kits available › OpenClaw Assistant Source: https://docs.diploi.com/building/starter-kits/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. ![Browser terminal for OpenClaw](/_astro/OpenClawTerminal.CFTyKOFK_2o3niR.webp) * Fully configured gpt-4.1-nano model, provided through the Diploi AI gateway. ![gpt-4.1-nano for OpenClaw](/_astro/OpenClawModels.BCsuScKf_ZTpwiO.webp) ## Launch [Launch OpenClaw Assistant on Diploi](https://diploi.com/starter-kit/openclaw) to create a new project from this starter kit. Like any Diploi project, it can be extended with more [components](/building/components) and [add-ons](/building/add-ons) through its `diploi.yaml` file. ## 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, through the [AI Gateway](/reference/ai-gateway) | ## 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 ## Control panel Once launched, a welcome page unique to Diploi lets you: * 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 ![Welcome page for OpenClaw](/_astro/OpenClawWelcomePage.CXfehaKs_TLfvY.webp) The OpenClaw dashboard itself hasn’t been modified, so you can expect the exact experience you would get if you configured OpenClaw manually. How the wrapper works, its API endpoints and environment variables are described in the readme below. ## Readme OpenClaw Starter Kit for running a self-hosted OpenClaw in Diploi Development Environment with: * A wrapper server (`server/`) that initializes config, manages the OpenClaw gateway, and exposes control APIs * A React/Vite control UI (`web/`) Version 2.0 updates the bundled OpenClaw runtime to `v2026.8.1` and introduces a secure owner-handoff flow for opening the OpenClaw dashboard. ### ✨ Overview On startup, the wrapper: 1. Initializes `/app/openclaw.json` (if missing) via `openclaw onboard` 2. Patches config defaults (gateway token, model provider, channel/plugin defaults) 3. Starts and monitors the OpenClaw gateway on `127.0.0.1:18789` 4. Proxies: * `/dashboard` to OpenClaw gateway UI * all other app routes to the Vite frontend #### Dashboard access in v2.0 Selecting **Open dashboard** opens a loading page while the wrapper requests a signed owner-handoff URL from OpenClaw. The browser then opens the dashboard on the public application origin, preserving the signed handoff data without exposing the gateway’s internal URL. For compatibility with older OpenClaw releases that do not support owner-handoff URLs, the wrapper falls back to the existing gateway-token flow. ### 🧱 Architecture #### Requirements * Diploi’s Development Environment * Node.js 22+ * npm * OpenClaw runtime available as either: * `openclaw` on `PATH`, or * `/lib/openclaw/dist/index.js` (provided in this repo’s Docker images) #### Environment Variables Common variables used by the wrapper: * `PORT` (default: `3000`) * `HOSTNAME` (default: `0.0.0.0`) * `VITE_HOST` (default: `127.0.0.1`) * `VITE_PORT` (default: `5173`) * `OPENCLAW_CONFIG_PATH` (default: `/app/openclaw.json`) * `OPENCLAW_STATE_DIR` (default: `/app`) * `OPENCLAW_WORKSPACE_DIR` (default: `/app/workspace`) * `OPENCLAW_GATEWAY_TOKEN` (optional; generated if missing) * `DIPLOI_AI_GATEWAY_URL` / `DIPLOI_AI_GATEWAY_TOKEN` (optional model proxy wiring) * `DIPLOI_LOGIN_SECRET` (required to validate `diploi-jwt-login` cookie) * `DIPLOI_LOGIN_USERNAME` / `DIPLOI_LOGIN_PASSWORD` (credential login) #### Development Workflow Install dependencies: ```bash npm install ``` Run dev mode (process manager + wrapper API + Vite UI): ```bash npm run dev ``` This starts: * `server/processManager.ts` * `server/index.ts` (Hono wrapper API) * `web` Vite dev server #### API Endpoints Wrapper endpoints: * `GET /healthz` * `GET /dashboard-loading` (temporary page shown while the dashboard handoff is created) * `GET /api/dashboard-link` (returns the signed dashboard handoff path, with a legacy token fallback) * `GET /api/dashboard-token` (legacy compatibility) * `GET /api/gateway/status` * `POST /api/gateway/start` * `POST /api/gateway/stop` * `POST /api/gateway/restart` * `POST /api/full-reset` * `POST /api/logout` * `WS /api/terminal-ws` (browser terminal) #### Project Structure ```text 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 utils/ dashboardLoading.ts # dashboard handoff loading page web/ src/ # React UI Dockerfile.dev # full dev image including OpenClaw build Dockerfile # production runtime image diploi.yaml # Diploi starter metadata ``` ## See also * [Using Starter Kits](/building/starter-kits) * [OpenClaw Assistant starter kit repository](https://github.com/diploi/starter-openclaw) * [OpenClaw GitHub](https://github.com/openclaw/openclaw) * [AI Gateway](/reference/ai-gateway) * [OpenClaw Documentation](https://docs.openclaw.ai/) * [Learn more about the `diploi.yaml` file](/reference/diploi-yaml) # Building › Starter Kits available › Chat App Source: https://docs.diploi.com/building/starter-kits/chat > 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. ## Launch [Launch Chat App on Diploi](https://diploi.com/starter-kit/chat) to create a new project from this starter kit. Like any Diploi project, it can be extended with more [components](/building/components) and [add-ons](/building/add-ons) through its `diploi.yaml` file. ## Tech stack | Technology | Role | | -------------- | ---------------------------------- | | **Next.js** | Full-stack React framework | | **Supabase** | Backend (database, auth, realtime) | | **TypeScript** | Language | Note Supabase brings its own PostgreSQL database, authentication and realtime features. The emails of the authentication flow are sent through Diploi’s [built-in email service](/reference/built-in-email). ## Readme A Slack like chat app built with **Next.js** and **Supabase**. This starter kit demonstrates: * 🔐 Authentication with Supabase * ⚡️ Next.js -powered React frontend * 🗄️ Supabase DB migrations and seeded data *** ### ✨ Overview This starter kit consists of two Diploi components: * **`next`** – Frontend application (Next.js) * **`supabase`** – Database, auth, and realtime backend Everything is wired together automatically via environment variables defined in `diploi.yaml`. *** ### 🔑 Default Login Credentials The database is seeded with a test account: Email: `test@example.com`\ Password: `password` You can log in immediately after deployment. > ⚠️ Make sure to change or remove this account in production environments. *** ### 🚀 Running on Diploi #### Start a new project 1. Create a new project in Diploi 2. Select this starter kit 3. Deploy Diploi automatically: * Connects Supabase to Next.js * Injects environment variables * Configures networking * Builds production images * Enables edge delivery via Cloudflare *** ### 💡 About Supabase This project is originally based on the [nextjs-slack-clone](https://github.com/supabase/supabase/tree/master/examples/slack-clone/nextjs-slack-clone) and adapted for Diploi deployments. Supabase is the Postgres development platform:\ ## See also * [Using Starter Kits](/building/starter-kits) * [Chat App starter kit repository](https://github.com/diploi/starter-chat) * [Next.js component](/building/components/next) * [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) # Building › Starter Kits available › Collaborative Drawing App Source: https://docs.diploi.com/building/starter-kits/refine-pixels > A collaborative pixel art drawing application starter kit built with Refine and Supabase, featuring realtime multi-user canvas support and authentication. The Collaborative 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. ## Launch [Launch Collaborative Drawing App on Diploi](https://diploi.com/starter-kit/refine-pixels) to create a new project from this starter kit. Like any Diploi project, it can be extended with more [components](/building/components) and [add-ons](/building/add-ons) through its `diploi.yaml` file. ## Tech stack | Technology | Role | | -------------- | ------------------------------------------- | | **Refine** | React-based CRUD framework, on React + Vite | | **Supabase** | Backend (database, auth, realtime) | | **TypeScript** | Language | Note The emails of the authentication flow are sent through Diploi’s [built-in email service](/reference/built-in-email). ## Readme A fun, collaborative drawing app built with **Refine**, **React (Vite)** and **Supabase**. This starter kit demonstrates: * 🔐 Authentication with Supabase * 🎨 Realtime collaborative updates * ⚡️ Vite-powered React frontend * 🗄️ Supabase DB migrations and seeded data *** ### ✨ Overview This starter kit consists of two Diploi components: * **`react-vite`** – Frontend application (Refine + React + Vite) * **`supabase`** – Database, auth, and realtime backend Everything is wired together automatically via environment variables defined in `diploi.yaml`. *** ### 🧱 Architecture #### 1️⃣ React (Vite) Component Based on the official Diploi [react-vite](https://github.com/diploi/component-react-vite) component. #### Environment Variables These are automatically injected from the Supabase component: * `VITE_SUPABASE_URL` * `VITE_SUPABASE_ANON_KEY` This starter kit enables Diploi’s **runtime build** mode: ```plaintext - name: __VITE_RUNTIME_BUILD value: true ``` This allows environment variables to be populated correctly in production deployments. *** #### 2️⃣ Supabase Component Based on the official Diploi [supabase](https://github.com/diploi/component-supabase) component. The component automatically configures redirect URLs so authentication flows correctly back to the React app. *** ### 🔑 Default Login Credentials The database is seeded with a test account: Email: `test@example.com`\ Password: `password` You can log in immediately after deployment. > ⚠️ Make sure to change or remove this account in production environments. *** ### 🚀 Running on Diploi #### Start a new project 1. Create a new project in Diploi 2. Select this starter kit 3. Deploy Diploi automatically: * Connects Supabase to React * Injects environment variables * Configures networking * Builds production images * Enables edge delivery via Cloudflare *** ### 💡 About Refine This project is originally based on the [Refine example template Pixels](https://refine.dev/core/templates/supabase-crud-app/) and adapted for Diploi deployments. Refine is a headless React framework for building CRUD applications:\ ## See also * [Using Starter Kits](/building/starter-kits) * [Collaborative Drawing App starter kit repository](https://github.com/diploi/starter-refine-pixels) * [React + Vite component](/building/components/react-vite) * [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) # Building › Starter Kits available › Web App Source: https://docs.diploi.com/building/starter-kits/web-app > A modern, production-ready template for building full-stack React applications using React Router and Supabase, 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, a Supabase backend, and an AI-friendly project structure, without spending time on boilerplate setup. ## Launch [Launch Web App on Diploi](https://diploi.com/starter-kit/web-app) to create a new project from this starter kit. Like any Diploi project, it can be extended with more [components](/building/components) and [add-ons](/building/add-ons) through its `diploi.yaml` file. ## Tech stack | Technology | Role | | ---------------- | ---------------------------------------- | | **React** | UI framework | | **React Router** | Routing and SSR | | **Supabase** | Backend (database, auth, edge functions) | | **TailwindCSS** | Styling | | **TypeScript** | Language | ## Readme A production-ready React Router + Supabase starter that showcases SSR, runtime ENV wiring, Tailwind CSS styling, and Supabase-backed data flows. This starter kit demonstrates: * 🔐 Supabase API access with typed helpers * ⚡️ React Router SSR + Vite dev experience * 🎨 Tailwind CSS styling with sensible defaults * 🗄️ Supabase migrations, seeds, and Edge Functions * 🧩 Diploi-managed components, ENV, and deployment automation *** ### ✨ Overview This starter kit consists of two Diploi components configured in [diploi.yaml](https://github.com/diploi/starter-web-app/blob/main/diploi.yaml): * **`react`** — React Router application (Vite, SSR, Tailwind, TypeScript) * **`supabase`** — Database, auth, migrations, seed data, Edge Functions Diploi automatically wires the components together by injecting `SUPABASE_URL` and `SUPABASE_ANON_KEY` into the React component at runtime. No manual `.env` files are required in any environment. *** ### 🧱 Architecture #### 1️⃣ React (React Router) Component * Based on the Diploi [react-vite](https://github.com/diploi/component-react-vite) component and the official React Router starter. * The app shell lives in [app/root.tsx](https://github.com/diploi/starter-web-app/blob/main/app/root.tsx) with SSR, streaming, and document links already configured. * Runtime environment variables load through the route `loader` exported from [app/lib/useEnv.ts](https://github.com/diploi/starter-web-app/blob/main/app/lib/useEnv.ts), ensuring the browser only receives the variables Diploi injects. * [app/lib/useSupabase.ts](https://github.com/diploi/starter-web-app/blob/main/app/lib/useSupabase.ts) exposes a singleton Supabase browser client backed by those ENV variables. * The landing view in [app/welcome/welcome.tsx](https://github.com/diploi/starter-web-app/blob/main/app/welcome/welcome.tsx) explains Diploi development workflow and renders a Supabase-powered todo demo via [app/welcome/supabase.tsx](https://github.com/diploi/starter-web-app/blob/main/app/welcome/supabase.tsx). * Styling is handled with Tailwind CSS (already wired up through Vite) plus a minimal set of custom classes inside [app/app.css](https://github.com/diploi/starter-web-app/blob/main/app/app.css). ##### Environment Variables Access ENV values with the `useEnv` helper hook. #### 2️⃣ Supabase Component * Based on the Diploi [supabase](https://github.com/diploi/component-supabase) component. * Ships with a `todos` table defined in [supabase/migrations/20260120083000\_todo.sql](https://github.com/diploi/starter-web-app/blob/main/supabase/migrations/20260120083000_todo.sql) and sample rows in [supabase/seed.sql](https://github.com/diploi/starter-web-app/blob/main/supabase/seed.sql). * Includes Edge Functions scaffolding inside [supabase/functions](https://github.com/diploi/starter-web-app/blob/main/supabase/functions) with a `main` router ([supabase/functions/main/index.ts](https://github.com/diploi/starter-web-app/blob/main/supabase/functions/main/index.ts)) and a `hello` example ([supabase/functions/hello/index.ts](https://github.com/diploi/starter-web-app/blob/main/supabase/functions/hello/index.ts)). * Works seamlessly with the Supabase Studio bundled in the component. Diploi exposes the correct connection strings via the Diploi Console. *** ### 💡 Docs * [React Router](https://reactrouter.com) * [Diploi Remote Development](https://diploi.com/dev) * [diploi.yaml reference](https://diploi.com/yaml) * [Supabase CLI & migrations](https://github.com/diploi/starter-web-app/blob/main/supabase/README.md) Build something great! 🚀 ## See also * [Using Starter Kits](/building/starter-kits) * [Web App starter kit repository](https://github.com/diploi/starter-web-app) * [React + Vite component](/building/components/react-vite) * [Supabase component](/building/components/supabase) * [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) # Building › Connecting via SSH Source: https://docs.diploi.com/building/add-ssh-key > Diploi utilizes SSH keys for user authentication when establishing SSH connections to deployments. Diploi utilizes SSH keys for user authentication when establishing SSH connections to deployments. This authentication method is commonly employed for remote development connections, such as those established through VS Code. To add an SSH key to your Diploi profile, you must: * Generate an SSH key pair * Copy the public SSH key * Add the copied content of your public SSH in Diploi That’s it 🙂 Let’s go through each step in detail. ## Generate a new SSH Key pair * Linux 1. Open a terminal and run: `ssh-keygen` which generates by default an ed25519 key pair. 2. You will get a message, asking you to assign a name for the key pair. ```bash Generating public/private ed25519 key pair. Enter file in which to save the key (/home//.ssh/id_ed25519): ``` 3. After that, you will be prompted to add a passphrase. ```bash Enter passphrase (empty for no passphrase): Enter the same passphrase again: ``` 4. Now your new key pair is ready, you will see the following message: ```bash Your identification has been saved in Your public key has been saved in someKey.pub The key fingerprint is: SHA256:gBVtt/m4zes+/0SZPkd+1wwo @ The key's randomart image is: +--[ED25519 256]--+ | o.. | | o . | | . . . | | . o o. .| | . S .= o.| | o o= o . B| | . o o .o.E .=*| | =.+o+..o +..=o| | .+B*=.. . ooo+| +----[SHA256]-----+ ``` * Windows 1. Using Git Bash, Terminal or WSL run: `ssh-keygen` which generates by default an ed25519 key pair. 2. You will get a message, asking you to assign a name for the key pair. ```bash Generating public/private ed25519 key pair. Enter file in which to save the key (/home//.ssh/id_ed25519): ``` 3. After that, you will be prompted to add a passphrase. ```bash Enter passphrase (empty for no passphrase): Enter the same passphrase again: ``` 4. Now your new key pair is ready, you will see the following message: ```bash Your identification has been saved in Your public key has been saved in someKey.pub The key fingerprint is: SHA256:gBVtt/m4zes+/0SZPkd+1wwo @ The key's randomart image is: +--[ED25519 256]--+ | o.. | | o . | | . . . | | . o o. .| | . S .= o.| | o o= o . B| | . o o .o.E .=*| | =.+o+..o +..=o| | .+B*=.. . ooo+| +----[SHA256]-----+ ``` * Mac 1. Open Terminal and run: `ssh-keygen` which generates by default an ed25519 key pair. 2. You will get a message, asking you to assign a name for the key pair. ```bash Generating public/private ed25519 key pair. Enter file in which to save the key (/home//.ssh/id_ed25519): ``` 3. After that, you will be prompted to add a passphrase. ```bash Enter passphrase (empty for no passphrase): Enter the same passphrase again: ``` 4. Now your new key pair is ready, you will see the following message: ```bash Your identification has been saved in Your public key has been saved in someKey.pub The key fingerprint is: SHA256:gBVtt/m4zes+/0SZPkd+1wwo @ The key's randomart image is: +--[ED25519 256]--+ | o.. | | o . | | . . . | | . o o. .| | . S .= o.| | o o= o . B| | . o o .o.E .=*| | =.+o+..o +..=o| | .+B*=.. . ooo+| +----[SHA256]-----+ ``` Note Alternatively, you can use an existing SSH key. * [How to check for existing keys?](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys) * [How to create an SSH key? walkthrough by GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) ## Copy the public key generated * Linux 1. ssh-keygen generates two files, one with an extension `.pub` and the other without any extension, eg. `someKey.pub` and `someKey`. The one we need right now is `someKey.pub`, which is your public key. You need to copy the contents of your `.pub` file. You can use the `cat` command: ```bash cat someKey.pub ``` 2. By using `cat` you will print the content of the `someKey.pub` file, it will look like this: ```bash ssh-ed25519 AA786grtyreugigyuwifewy65643354qWrjhBLtBSewyweRTIZw5DqD0zj @ ``` All you need to do is copy the entire output. * Windows 1. ssh-keygen generates two files, one with an extension `.pub` and the other without any extension, eg. `someKey.pub` and `someKey`. The one we need right now is `someKey.pub`, which is your public key. You need to copy the contents of your `.pub` file. You can use the `cat` command: ```bash cat someKey.pub ``` 2. By using `cat` you will print the content of the `someKey.pub` file, it will look like this: ```bash ssh-ed25519 AA786grtyreugigyuwifewy65643354qWrjhBLtBSewyweRTIZw5DqD0zj @ ``` All you need to do is copy the output. * Mac 1. ssh-keygen generates two files, one with an extension `.pub` and the other without any extension, eg. `someKey.pub` and `someKey`. The one we need right now is `someKey.pub`, which is your public key. You need to copy the contents of your `.pub` file. You can use the `cat` command: ```bash cat someKey.pub ``` 2. By using `cat` you will print the content of the `someKey.pub` file, it will look like this: ```bash ssh-ed25519 AA786grtyreugigyuwifewy65643354qWrjhBLtBSewyweRTIZw5DqD0zj @ ``` All you need to do is copy the entire output. Note Having trouble finding your public key? Check this thread from StackOverflow about [how to find the public key](https://stackoverflow.com/questions/3828164/how-do-i-access-my-ssh-public-key/3828169#3828169). ## Add your public key in Diploi Now that you copied the contents of your public key, you need to add it to your Diploi profile: 1. Go to [your profile settings](https://console.diploi.com/settings). 2. Select “Add new SSH key”. 3. Provide a description for your key, such as “Work MacBook,” to help you remember its origin or purpose. 4. Paste your SSH “public key” into the designated field. 5. Click the “Add SSH Key” button. ![Add SSH Key](/_astro/AddSSHKey.CyuoedUv_Z2iUQD9.png) 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. # Building › Using Remote Development Source: https://docs.diploi.com/building/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 cloud IDE, or connect to them using your favorite IDE via SSH. ![Cloud IDE](/_astro/DeploymentOverviewDevelopment.C6YBQH-1_ZgcpAj.png) ### Using Diploi’s Cloud IDE Diploi offers a built-in cloud 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 cloud 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 cloud IDE in a new tab. The cloud IDE is preconfigured with Diploi models through the [AI Gateway](/reference/ai-gateway). Continue is ready in the editor, and the OpenCode CLI is available in the terminal. You can also use the **Prompt** view on the deployment page in the console to describe changes in natural language. No OpenAI or Anthropic API keys are required. Usage is billed from your Diploi balance. ### 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. ![Add IDE to deployment](/_astro/DevelopmentLocalIde.D3nySK3z_g9xoH.png) Note You can pin your preferred IDE to the top of the list of available IDEs by clicking on the pin icon next to the IDE name. Caution If you are developing on a Windows machine with WSL enabled, please note that a Windows VS Code install uses SSH keys on your **Windows** user by default. #### Configuration Your local VS Code configuration will be used for all remote environments, but certain features (like extensions) need to be configured on a per-deployment basis. ### Other IDEs Caution Diploi currently has built-in persistent configuration for VS Code only. This means that you will have to configure/install your other IDE again after a deployment upgrade. Diploi supports any IDE capable of connecting to a remote machine via SSH. This includes terminal-based IDEs like Vim. #### Terminal Based IDEs Simply open an SSH connection to your deployment, and install your favorite IDE. # Reference › The Diploi CLI Source: https://docs.diploi.com/reference/diploi-cli > Inspect and control a deployment from its development environment with the diploi command. Every Diploi development environment comes with the `diploi` command (short: `dip`). It works on the deployment you are in: what is running, how it is configured, and what the logs and Kubernetes events say. It also runs commands in your containers, restarts them, and applies the changes you made to `diploi.yaml`. Your editor and terminal run in their own container, the **development environment**, which is separate from the containers your components run in. Both see the same code in `/app`, so a file you edit here is the file they run. Use `diploi exec` when something has to run inside a component’s container, with its runtime and its environment. `diploi` only works from the development environment. ```bash diploi status # is everything running? diploi describe # what is in this deployment, and what is in my environment? diploi logs api # what is my component saying? ``` Note Run `diploi` with no arguments to see the commands. `diploi help ` and `diploi --help` show the options and examples of one command. ## Naming things Most commands take a **component**: the `identifier` of a component or add-on in `diploi.yaml`, such as `api`, `postgres` or `supabase`. That is all you normally need. The CLI picks the running pod and the component’s main container for you, and tells you which one it picked when there is more than one. Some components run several workloads. Supabase, for example, runs a dozen. Name one after the component to pick it: `diploi logs supabase db` reads the `db` pod. A full pod name works too. Name a container after the pod, as in `diploi logs supabase db postgres`, or use `-c ` to pick one without naming a pod. ## Commands | Command | What it does | | ------------------------------------------------- | ------------------------------------------------------------------------------- | | [`diploi status`](#diploi-status) | Components, pods, addresses and anything that needs attention | | [`diploi describe [component]`](#diploi-describe) | Configuration: paths, addresses, environment variables and where they come from | | [`diploi logs `](#diploi-logs) | Recent logs of a component, or a live stream | | [`diploi events [component]`](#diploi-events) | Kubernetes events: why a pod restarted or failed to start | | [`diploi exec `](#diploi-exec) | A shell, or one command, inside a container | | [`diploi restart `](#diploi-restart) | Restart a component and wait for the new pod | | [`diploi apply`](#diploi-apply) | Apply the pending `diploi.yaml` changes | | [`diploi components [query]`](#diploi-components) | Components and add-ons you can add, with their versions and `diploi.yaml` entry | | [`diploi agents init`](#diploi-agents) | Connect your AI clients to this deployment through the Diploi MCP server | Every command also accepts `--json`, which prints the same information as JSON instead of text. That is useful in scripts and for AI agents working in the environment. Streaming commands print one JSON object per line. ### `diploi status` The state of the whole deployment: * Every component with its state (`ok`, `starting`, `problem` or `no pods`), public url and internal addresses * Its pods with phase, readiness, restarts and age * The `diploi.yaml` changes that are not applied yet, with a heads-up when applying them needs care (see [Adding a component](#adding-a-component)) * A **Problems** list in plain words, such as a container stuck in `CrashLoopBackOff`, an image that cannot be pulled, or a configuration error A deployment that is only starting up is not a problem, so an empty list means there is nothing to look into. ```bash diploi status diploi status --json ``` ### `diploi describe` What the deployment is configured with. This is the applied configuration, not the file on disk. Without a component it describes the deployment: its components and the folder each one lives in, the environment variables available in your development environment, and the init commands. Every variable is listed with the component it came from. ```bash diploi describe ``` With a component it describes that component: * The folder of its code, its main container and the commands it starts with * Its image, volumes, public url and internal addresses * Its parameters and connection strings * Every environment variable **with its origin**: a parameter from the **Setup** tab, a value from the **Environment** tab, a static value in `diploi.yaml`, a default from the package, an import from another component, the component’s own address, or a built-in Diploi variable such as `DIPLOI_NAMESPACE` ```bash diploi describe postgres diploi describe postgres --reveal # with the secret values ``` Secret values are masked unless you pass `--reveal`. ### `diploi logs` The last 200 lines of a component’s log, or a live stream with `--follow`. `diploi log` works too. ```bash diploi logs api diploi logs api --follow diploi logs api --since 10m # a time window instead of a line count diploi logs api --previous # the log of the container that crashed diploi logs api --all-containers # including init and sidecar containers ``` | Option | | | -------------------------- | --------------------------------------------------------------- | | `-f, --follow` | Stream new lines as they arrive | | `-n, --lines ` | Lines to show, `0` for all (default 200, or all with `--since`) | | `--since ` | Only newer than e.g. `30s`, `10m`, `2h`, `1d` | | `--since-time ` | Only after an RFC3339 timestamp | | `--timestamps` | A timestamp on every line | | `-p, --previous` | The previously terminated container instance | | `--all-containers` | Every container of the pod, each line tagged | | `-c, --container ` | A specific container | | `-q, --quiet` | Do not print which pod was picked | ### `diploi events` The Kubernetes events of the deployment, oldest first: pods being scheduled and started, images pulled, probes failing, containers backing off. Look here when a pod never reaches a running state and its log is empty. ```bash diploi events # the newest 100 events diploi events api --since 10m diploi events -w # only warnings diploi events -n 20 # only the newest 20 ``` ### `diploi exec` Runs something inside a component’s container. Without a command it opens an interactive shell. With a command after `--` it runs that one command and returns its exit code. ```bash diploi exec api # a shell in the api container diploi exec api -- npm install lodash # install a dependency where it runs diploi exec api -- npm run migrate diploi exec api -- sh -c 'npm run build && npm start' cat dump.sql | diploi exec postgres -- psql -U postgres ``` The command runs as it is, without a shell. For pipes, `&&` or the container’s own variables, wrap it in `sh -c '…'` as above. The single quotes also keep your own terminal from expanding anything first. `-u 1000:1000` runs as another user, and `-t` forces a TTY for commands that expect one. `--no-tty` turns the TTY off, and `--no-stdin` does not pass your input to the command. Tip Code dependencies, like npm or pip packages, are installed when the pod starts. You can also install them yourself, either with `diploi exec` or in the component’s folder from your own terminal, because both see the same files in `/app`. A system package is different. One installed with `diploi exec` is gone when the component restarts, so add it to the component’s `Dockerfile` and `Dockerfile.dev` instead. For a tool you only need in your own terminal, use [`development.initCommands`](/reference/diploi-yaml#developmentinitcommands). ### `diploi restart` Restarts a component by deleting its pod, and the deployment immediately creates a new one. The command waits until the new pod is running and ready, so it is finished when the component is back. It waits up to 2 minutes, and exits with code `2` when no new pod becomes ready in that time. ```bash diploi restart api diploi restart supabase db # one workload of a multi-workload component diploi restart supabase --all # every pod of the component diploi restart api --timeout 300 # wait up to 5 minutes (at most 600 seconds) diploi restart api --no-wait ``` ### `diploi apply` Applies the changes you made to `diploi.yaml`, such as added or removed components and add-ons, changed environment imports and changed versions. This is what the **Apply changes** button in the Console does. `diploi status` shows what is pending before you apply. A change to `diploi.yaml` takes a few seconds to be checked, and `diploi apply` right after saving waits for that first, so it always applies the file as it is. It then waits until every new and changed component is deployed and ready, and lists each one with its state, folder and public url. Removed components are waited for too, until their pods are gone. When a component fails, for example because its container keeps crashing, or is not ready before the timeout, the command says so and exits with code `2`. ```bash diploi status # "Pending changes" lists what would be applied diploi apply # wait for the changed components, up to 5 minutes diploi apply --timeout 600 diploi apply --no-wait # return right after applying ``` Applying acts as the user assigned to the deployment in the Console (under **Git**), or as the user who created the deployment when the project has no repository. #### Adding a component When you add a component to `diploi.yaml`, applying creates its folder (`/app/`, or its `folder`) from the component’s starter: its `Dockerfile` and `Dockerfile.dev`, its configuration and its starter code. This only happens when the folder does not exist yet, so add the component and apply first, then build on the starter. If the folder already exists, for example because you are adding a component for code you already have, it is left as it is and the component gets none of the starter files. Both `diploi status` and `diploi apply` point this out. Staging and production builds need the `Dockerfile`, so add it yourself in that case. Note Changing the environment variables or the [`development.initCommands`](/reference/diploi-yaml#developmentinitcommands) of the development environment restarts it when you apply: running processes stop, and tools installed outside `/app` and the home folder have to be installed again. `diploi apply` answers right away in that case, without waiting for the components. ### `diploi components` The components and add-ons you can add to `diploi.yaml`: the same list the Console offers, with the versions that exist. With a query (an identifier, a name or a few words) it shows the matches in detail: every version, the environment variables other components can import from it, the add-ons it needs, and the entry to paste into `diploi.yaml`. ```bash diploi components # everything that can be added diploi components next # versions and the diploi.yaml entry of Next.js diploi components react ssr # everything matching "react ssr" ``` Use one of the listed versions: a version that does not exist makes `diploi.yaml` fail to apply, and `diploi status` then lists the versions that do. The entry includes the add-ons a component needs, such as the database of Odoo; leave out the ones your `diploi.yaml` already has. ### `diploi agents` Sets up the AI clients you bring along, so they can use the tools of this deployment. Claude Code, Codex and Gemini CLI get the Diploi MCP server and are pointed at the instructions in `/etc/diploi/AGENTS.md`. VS Code gets the MCP server only. Cursor is only configured with `--project`, which writes `AGENTS.md` and `.cursor/mcp.json` into the project. Your existing settings are kept, and only what is missing is added. OpenCode and Continue come with the development environment and Diploi configures them itself (see [Built-in tools](/reference/ai-gateway#built-in-tools)), so they need nothing from you. ```bash diploi agents init # configure the clients that are not configured yet diploi agents init --project # also write AGENTS.md and .cursor/mcp.json into the project diploi agents init --force # configure every client again, also the ones you changed ``` This already runs when the development environment starts, and each client is configured only once, so a file you delete or change is not touched again. Run it yourself with `--force` to restore files you deleted or changed, or with `--project` to add the project files. ## See also * [Using Remote Development](/building/remote-development) * [diploi.yaml Explained](/reference/diploi-yaml) * [Troubleshooting](/troubleshooting) # Reference › Technical Deep Dive Source: https://docs.diploi.com/reference/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). # Reference › Diploi Project Architecture Source: https://docs.diploi.com/reference/architecture > A high level explanation of how Diploi works and how projects are setup. ## Diploi in a Nutshell Diploi’s mission is to make deployment into a process that you do not need to think about. Our goal is for you to just focus on the code that defines your app, without worrying about SSL certificates, setting up CI/CD pipelines and other commonly cursed devops demons. We made it possible with a simple architecture to define a new application. In Diploi, you start by first creating a **Project**. A project is the basic building block of your new application. Inside your **Project**, you define the elements that will power your application. There are two types of elements that are part of your **Project**, * **Components**, which are the elements that will be exposed for users to access them. These can be frontend, backend or fullstack, and inside of a project you can have multiple components running at the same time as a monorepo. * **Add-ons**, which are elements that will be accessible to your components only. These can be databases, cache servers, message queues, etc. Note You can have as many components and add-ons in your project as you want 🙂 ### Project Structure To make the following explanations clearer, let’s assume we just created a Project with Bun for the backend and React+vite for the frontend, Redis for caching and PostgreSQL as our app’s database. ![Project example](/_astro/ProjectExample._-aIORQt_B9yvn.svg) ### 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. ![Deployment example](/_astro/DeploymentExample.DYBwP4S6_ZGuTU8.svg) 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. ![Deployment container structure](/_astro/DeploymentContainers.C06bLwHf_ywtLV.svg) 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. ![Project example with deployments](/_astro/ProjectExampleWithDeployments.CLpTmx23_17awcM.svg) *** 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). # Reference › diploi.yaml Explained Source: https://docs.diploi.com/reference/diploi-yaml > The configuration file that defines the components, add-ons and development environment of a project. 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. The component-based model keeps the file short. The detailed configuration of a component, such as its Helm charts and other setup files, lives in a dedicated GitHub repository maintained by the component owners. Tip Read our blog post about our [IaC implementation](https://dev.to/diploi/how-we-solved-infrastructure-as-code-2ldn) for more information. ```yaml diploiVersion: v1.0 development: env: include: - postgres.* 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 ``` The file has three top-level sections: [`components`](#components-and-addons) and [`addons`](#components-and-addons) describe what the deployment runs, and [`development`](#development) describes the environment you work in. `diploiVersion` is always `v1.0`. After editing the file, apply the changes from the deployment’s **Overview** in the Console, or run [`diploi apply`](/reference/diploi-cli#diploi-apply) in the development environment. `diploi status` shows what is pending before you apply. ## `components` and `addons` The components and add-ons the deployment runs. Edit this list and the infrastructure adapts. To add one, take its entry from the component’s page in these docs, or from [`diploi components`](/reference/diploi-cli#diploi-components) in the development environment, and apply the change before you write code in its folder. Applying creates the folder from the component’s starter (its `Dockerfile`, `Dockerfile.dev`, configuration and starter code), but only when the folder does not exist yet. ### `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` Where the files of a component live in your repository. Use it when you import an existing application whose code is already in a folder of its own. The path is relative to the root of the repository and **has to start with a `/`**: `/api`, or `/` when the component is the repository root. If the folder already exists, Diploi generates no new files and runs the component from the files it finds there. Note Add a `Dockerfile` (used by staging and production) and a `Dockerfile.dev` (used by development) to that folder if you run staging or production stages, or if you need to change how the component starts. You can get all of our officially supported Dockerfiles for all components [in our GitHub repositories](https://github.com/orgs/diploi/repositories). ### `package` The URL for the package repository. Version comes after the hashtag `#` symbol. Version can be a Git tag or branch reference. ### `prebuildImage` An image to start the component from instead of building it from the repository, used by starter kits so a new deployment is running before the first build finishes. `[tag]` in the url is replaced with the version of the component. ```yaml components: - name: React identifier: react package: https://github.com/diploi/component-react-vite#v19.2.6 prebuildImage: public.ecr.aws/p8t2q7f4/diploi/starter-web-app/react:[tag] ``` ### `hosts` `hosts` declares the network endpoints a component exposes. Each entry maps a port inside the container to a public HTTPS endpoint, to an internal service name that only other components in the deployment can reach, or to both. Note Overriding a host that a component already declares works everywhere. Adding new hosts only works for components that support it. The page of each component lists the hosts it declares. ```yaml components: - name: Bun identifier: bun package: https://github.com/diploi/component-bun#main hosts: # Public endpoint, gets an SSL certificate and a configurable domain - identifier: api name: API port: 3000 # Internal only, reachable by other components but not from the internet - identifier: metrics name: Metrics endpoint: false port: 3001 ``` #### `hosts[].identifier` A unique slug for the host inside the component. It becomes part of the internal hostname other components use to reach the service, and of the variables its addresses are published as: `_ENDPOINT` for the public url and `_INTERNAL_ENDPOINT` for the internal one (see [Addresses of Other Components](#addresses-of-other-components)). The full hostname is in the Diploi Console and in [`diploi describe `](/reference/diploi-cli#diploi-describe). When it is left out, the identifier becomes `port-`. Using the same identifier as a host the component already declares overrides that host (its name, port or `endpoint`) instead of adding a new one. #### `hosts[].name` A human-readable label shown in the Diploi Console for this endpoint. #### `hosts[].port` The port your application listens on inside the container. #### `hosts[].endpoint` Controls whether the host is exposed publicly. Defaults to `true`. * **`true`**: Diploi provisions a public HTTPS endpoint with an automatically managed SSL certificate. Assign a `diploi.app` subdomain or a [custom domain](/deploying/custom-domain/) from the deployment’s **Options** tab. * **`false`**: The service is only reachable by other components in the same deployment, never from the public internet. ### `env` ENV values from other components are not available by default. Import them here to make them available to the processes inside a component. #### Import From Other Components Imports reuse the ENV values of other components, which keeps them in sync and avoids repeating configuration. Open the **Options** tab of a component to see the values it defines, the ones it imports, and to override any of them. ```yaml env: include: # Imports every ENV value from every component (quoted: a bare * is not valid YAML) - '*' # 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 ``` | Entry | Imports | | -------------------------------- | --------------------------------------------------------------------------- | | `'*'` | Every ENV value of every component (quote it, a bare `*` is not valid YAML) | | `postgres.*` | Every ENV value of the `postgres` component | | `postgres.POSTGRES_*` | The values of `postgres` that start with `POSTGRES_` | | `post*` | Every ENV value of every component whose identifier starts with `post` | | `postgres.POSTGRES_USER` | One value of `postgres` | | `postgres.POSTGRES_USER:DB_USER` | One value of `postgres`, renamed to `DB_USER` | #### Addresses of Other Components Every host of a component is published as variables other components can import: | Variable | Value | Use it for | | -------------------------- | -------------------------------- | --------------------------------------------------------- | | `_INTERNAL_ENDPOINT` | `http://app.odoo:8069` | Calls between components: they stay inside the deployment | | `_ENDPOINT` | `https://my-dev--odoo.diploi.me` | Links for browsers, or anything outside the deployment | `` is the host’s identifier in capitals (`app` becomes `APP_`, `admin-ui` becomes `ADMIN_UI_`). The internal endpoint is published only for hosts with a [`port`](#hostsport), and only for other components to import: the component itself does not get it. The development environment can import it too, under [`development.env`](#developmentenv). It is for server-side code: a browser cannot reach an internal address. `diploi describe ` lists a component’s addresses with the names to import them by. Importing a name a component does not publish gives nothing, without an error, so check there first. #### Compose Values From Imports A static value can use `${VARIABLE}` to refer to a variable the component has, including one it just imported. Use this to build a url or a connection string from what another component publishes, instead of writing that component’s address into the configuration: ```yaml components: - name: Astro identifier: astro package: https://github.com/diploi/component-astro#main env: include: - odoo.APP_INTERNAL_ENDPOINT:ODOO_URL - name: ODOO_CATALOG_URL value: '${ODOO_URL}/api/catalog/products' ``` A literal internal address (`http://app.odoo:8069`) contains another component’s identifier, service name and port, and stops working when any of them changes. Import the address the component publishes instead. #### 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 that declares them and stay the same across deployments. For runtime configuration use the **Options** tab, which can also override a static value without changing the file. ### `containerCommands` Overrides the commands a component’s container starts with. Every component has defaults, so use this when your project structure or tooling differs from what the component assumes. The alternative is to edit the command in the component’s `Dockerfile` (staging and production) or `Dockerfile.dev` (development). Use `containerCommands` to change it without touching the Dockerfiles. ```yaml components: - name: Astro identifier: astro package: https://github.com/diploi/component-astro#main containerCommands: developmentStart: bun run dev -- --host productionStart: bun start ``` Note This feature is only available for supported components. #### `containerCommands.developmentStart` The command used to start the container in a **development** deployment. This replaces the component’s default development start command. For example, the Astro component defaults to `npm run dev -- --host` and the FastAPI component defaults to `uv run --with uvicorn uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload --reload-dir src --reload-dir .venv/lib`. You can check the default command from the Dockerfile.dev. #### `containerCommands.productionStart` The command used to start the container in a **staging or production** deployment. This replaces the component’s default production start command. For example, the Astro component defaults to `npm start` and the FastAPI component defaults to `uv run --with uvicorn uvicorn src.main:app --host 0.0.0.0 --port 8000 --proxy-headers`. You can check the default command from the Dockerfile. ## `development` Configures the **development environment**, the container with your editor and terminal that you open from the Console or connect to over SSH. It is separate from the containers your components run in, but shares the same `/app` folder, so it is where you edit code, run git, and use [the Diploi CLI](/reference/diploi-cli). This section only affects development deployments. Staging and production ignore it. ```yaml development: initCommands: - apt-get install -y imagemagick env: include: - postgres.* - supabase.ANON_KEY:SUPABASE_ANON_KEY - name: APP_ENV value: development components: # ... ``` ### `development.env` Which environment variables are available in your terminal. A project created in the Stack Builder already imports the variables of every add-on, which is what makes `psql $POSTGRES_URL` or a migration script work from the terminal without copying credentials by hand. ENVs from components are not imported by default. The syntax is the same as [`env`](#env) on a component. ```yaml development: env: include: # Everything a component defines - postgres.* # One value, renamed - supabase.APP_ENDPOINT:SUPABASE_URL # A static value - name: APP_ENV value: development ``` Run `printenv` in the terminal to see them, or [`diploi describe`](/reference/diploi-cli#diploi-describe) to see each one with the component it came from. Changing this section restarts the development environment. ### `development.initCommands` Commands to run when the development environment starts, as `root`, before your terminal is available. Use them for tools your work needs but the base image does not have. ```yaml development: initCommands: - apt-get update - apt-get install -y imagemagick ``` The commands run on every start of the environment, not only the first, so they should be safe to repeat. They run in a shell that stops at the first failing command, and their output is in the development environment’s logs. Changing them restarts the environment. Note `initCommands` install things in the development environment only. To install something a component needs at runtime, put it in that component’s `Dockerfile` and `Dockerfile.dev`. For a quick test you can run [`diploi exec -- ...`](/reference/diploi-cli#diploi-exec), but it is gone on the next restart. ## Diploi placeholders Some values are filled in by Diploi at deployment time. Use them in `env.include` entries so each deployment gets the right credentials: ```yaml env: include: - name: DIPLOI_AI_GATEWAY_URL value: '{diploi-ai-gateway-url}' - name: DIPLOI_AI_GATEWAY_TOKEN value: '{diploi-ai-gateway-token}' ``` | Placeholder | Meaning | | --------------------------- | ------------------------------------------------------------ | | `{diploi-ai-gateway-url}` | Internal AI Gateway URL (`http://core.diploi/ai-core-proxy`) | | `{diploi-ai-gateway-token}` | Token for this deployment | These are resolved when the deployment starts, not at image build time. See [AI Gateway](/reference/ai-gateway). # Reference › GitHub Actions Source: https://docs.diploi.com/reference/github-action > How Diploi uses GitHub Actions to build and push container images for your components. Diploi automatically generates a GitHub Actions workflow in your repository at `.github/workflows/Build.yaml`. This workflow builds Docker images for each component in your stack and pushes them to the Diploi container registry whenever you push code to any branch. ## How it works The workflow runs in two jobs: 1. **Define Components** — reads your `diploi.yaml` and outputs a build matrix describing each component and environment that needs an image. 2. **Build** — runs in parallel for each matrix entry, building and pushing the Docker image using the [`diploi/action-build`](https://github.com/diploi/action-build) action. ## Default workflow ```yaml name: Build Components on: push: branches: - '*' jobs: define-components: name: Define Components runs-on: ubuntu-latest outputs: components: ${{ steps.diploi-meta.outputs.components }} steps: - name: Checkout code uses: actions/checkout@v3 - id: diploi-meta name: Diploi meta uses: diploi/action-components@v1.8 run-builds: name: Build ${{ matrix.name }} ${{ matrix.stage }} runs-on: ubuntu-24.04-arm needs: define-components strategy: fail-fast: false matrix: include: ${{ fromJSON(needs.define-components.outputs.components) }} steps: - name: Checkout code uses: actions/checkout@v3 - name: Diploi build uses: diploi/action-build@v1.12 with: ${{ matrix }} env: project: ${{ secrets.DIPLOI_REGISTRY_PROJECT }} registry: ${{ secrets.DIPLOI_REGISTRY_HOSTNAME }} username: ${{ secrets.DIPLOI_REGISTRY_USERNAME }} password: ${{ secrets.DIPLOI_REGISTRY_PASSWORD }} ``` ## Dockerfiles The build action selects the Dockerfile to use based on the target environment: * **`Dockerfile.dev`** — used for the **development** environment, if it exists in the component’s folder. * **`Dockerfile`** — used for **staging and production** environments, and as a fallback for development if `Dockerfile.dev` is not present. Both files are expected to be located inside the component’s folder (e.g. `my-api/Dockerfile`). Tip You can get the official Dockerfiles for all Diploi-supported components from the [Diploi GitHub repositories](https://github.com/orgs/diploi/repositories). Each component repository contains the `Dockerfile` and `Dockerfile.dev` used as defaults. ## Registry secrets The workflow expects four repository secrets to be configured. Diploi sets these automatically when you connect your repository. | Secret | Description | | -------------------------- | ----------------------------------------- | | `DIPLOI_REGISTRY_HOSTNAME` | Hostname of the Diploi container registry | | `DIPLOI_REGISTRY_PROJECT` | Project name within the registry | | `DIPLOI_REGISTRY_USERNAME` | Registry login username | | `DIPLOI_REGISTRY_PASSWORD` | Registry login password | ## Build arguments Static ENV values defined in `diploi.yaml` under a component’s `env` block are forwarded to the Docker build as `ARG` variables. See [Static Values](/reference/diploi-yaml#static-values) for details on how to define them. ## Exposing GitHub secrets to the build If your Dockerfile needs access to sensitive values during the build — such as a private npm registry token or an API key for a build-time fetch — you can pass GitHub repository secrets to the build action using Docker BuildKit’s secret mounting. Add a `secrets` key to the `env` block of the build step in your workflow: ```yaml - name: Diploi build uses: diploi/action-build@v1.12 with: ${{ matrix }} env: project: ${{ secrets.DIPLOI_REGISTRY_PROJECT }} registry: ${{ secrets.DIPLOI_REGISTRY_HOSTNAME }} username: ${{ secrets.DIPLOI_REGISTRY_USERNAME }} password: ${{ secrets.DIPLOI_REGISTRY_PASSWORD }} secrets: | NPM_TOKEN=${{ secrets.NPM_TOKEN }} ``` Then mount the secret in your `Dockerfile` using `--mount=type=secret`: ```dockerfile RUN --mount=type=secret,id=NPM_TOKEN \ NPM_TOKEN=$(cat /run/secrets/NPM_TOKEN) npm install ``` Secrets mounted this way are never stored in the image layers, only available during the `RUN` step that mounts them. Note GitHub repository secrets can be added under **Settings → Secrets and variables → Actions** in your repository. # Reference › Built-In Email Source: https://docs.diploi.com/reference/built-in-email > Use Diploi's internal SMTP relay for development-friendly email delivery. Diploi provides a lightweight SMTP relay inside every deployment so your applications can send email without provisioning an external provider. The service is intended for development and low-volume operational notifications.\ The SMTP relay is included with your deployment at no additional cost. ## Connection details Connect using these values: * Host: `core.diploi` * Port: `2525` * Authentication: Not required Note This SMTP relay is only reachable from processes running inside your Diploi deployment network. External services cannot connect. ### Example configuration ```ts import nodemailer from "nodemailer"; const transporter = nodemailer.createTransport({ host: "core.diploi", port: 2525, }); await transporter.sendMail({ to: "user@example.com", subject: "Verify your email", text: "Click the link in the email to verify your account.", }); ``` ## Component integration The Supabase component automatically points its email authentication workflows at this relay, giving you out-of-the-box email confirmation flows without additional configuration. ## Usage limits Caution The relay enforces strict rate limits to keep the service reliable for all tenants. * Maximum 10 messages per hour * Maximum 30 messages per day * Contact support if you need higher throughput ## Header normalization To protect deliverability, Diploi rewrites certain email headers. These headers are stripped if present: * `from` * `to` * `sender` * `reply-to` * `return-path` * `resent-from` * `resent-to` * `resent-sender` * `bcc` * `cc` * `errors-to` * `x-original-from` * `x-envelope-from` Diploi sets the `from` address to your project’s default domain for every message. ## Best practices * Use the relay for development and staging workloads; production-grade email should use a dedicated provider once you outgrow the limits. * Keep transactional content concise to avoid hitting daily limits. * Reach out to support if you need custom limits or additional deliverability controls. # Reference › AI Gateway Source: https://docs.diploi.com/reference/ai-gateway > Call OpenAI and Anthropic models from your Diploi deployment without managing API keys. Diploi provides an AI Gateway inside every deployment so your apps, agents and coding tools can use AI models without provider API keys. Usage is billed from the same account balance as your deployments. The gateway works with the OpenAI and Anthropic APIs and supports streaming. The cloud IDE, OpenCode and the Prompt view in the console already use it. ## Connection details Connect using these values from any process running inside your deployment: * Base URL: `http://core.diploi/ai-core-proxy` * Authentication: Bearer token, unique to each deployment Note The AI Gateway is only reachable from processes running inside your Diploi deployment network. Your laptop, CI and other hosts outside the deployment cannot connect. You do not need to copy these values by hand. Diploi fills them in for you when you use these placeholders in `diploi.yaml` (see [Using the gateway in a component](#using-the-gateway-in-a-component)): | Placeholder | Value | | --------------------------- | ---------------------------------- | | `{diploi-ai-gateway-url}` | `http://core.diploi/ai-core-proxy` | | `{diploi-ai-gateway-token}` | The token of this deployment | Development environments also have these environment variables set: | Environment variable | Value | | ------------------------ | ------------------------------------- | | `DIPLOI_AI_API_BASE_URL` | `http://core.diploi/ai-core-proxy/v1` | | `DIPLOI_AI_TOKEN` | The token of this deployment | Caution `{diploi-ai-gateway-url}` does not end with `/v1`, but `DIPLOI_AI_API_BASE_URL` does. Check which one you have before adding the path for your SDK. ### URL formats Add the path of the API you are calling to the gateway URL: * OpenAI: `{diploi-ai-gateway-url}/openai/v1` * Anthropic: `{diploi-ai-gateway-url}/anthropic` The gateway also accepts the older OpenAI-style path `{diploi-ai-gateway-url}/v1/...`, which is where `DIPLOI_AI_API_BASE_URL` points. On that path the gateway picks the provider from the `model` field. Kimi, GLM and Qwen models only work on the `/v1` path, not on `/openai/` or `/anthropic/`. ### Authentication Send the deployment token in one of these ways: * `Authorization: Bearer ` header * `x-api-key: ` header * `?key=` query parameter Each deployment has its own token, and cloning or re-enabling a deployment gives it a new one. Read the token from the environment instead of hard-coding it. ## Example configuration These examples read the URL and token from `DIPLOI_AI_GATEWAY_URL` and `DIPLOI_AI_GATEWAY_TOKEN`, which you can set up as shown in [Using the gateway in a component](#using-the-gateway-in-a-component). ### OpenAI SDK ```ts import OpenAI from "openai"; const openai = new OpenAI({ apiKey: process.env.DIPLOI_AI_GATEWAY_TOKEN, baseURL: `${process.env.DIPLOI_AI_GATEWAY_URL}/openai/v1`, }); const response = await openai.chat.completions.create({ model: "gpt-5.6-terra", messages: [{ role: "user", content: "Say hello from Diploi." }], }); ``` Streaming works the same way as with OpenAI (`stream: true`). In the cloud IDE you can use `process.env.DIPLOI_AI_TOKEN` and `process.env.DIPLOI_AI_API_BASE_URL` instead. That base URL already ends with `/v1`, so pass it to `baseURL` as it is. ### Anthropic SDK ```ts import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.DIPLOI_AI_GATEWAY_TOKEN, baseURL: `${process.env.DIPLOI_AI_GATEWAY_URL}/anthropic`, }); const message = await anthropic.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, messages: [{ role: "user", content: "Say hello from Diploi." }], }); ``` ### curl ```bash curl http://core.diploi/ai-core-proxy/openai/v1/chat/completions \ -H "Authorization: Bearer $DIPLOI_AI_GATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Say hello from Diploi."}] }' ``` ## Using the gateway in a component Add the placeholders as environment variables of the component that calls the gateway. Diploi fills them in when the deployment starts: ```yaml components: - name: Node.js identifier: api package: https://github.com/diploi/component-nodejs#main env: include: - name: DIPLOI_AI_GATEWAY_URL value: '{diploi-ai-gateway-url}' - name: DIPLOI_AI_GATEWAY_TOKEN value: '{diploi-ai-gateway-token}' ``` You can also set these variables in the **Options** tab of the deployment. The placeholders work in any environment variable, so you can use the names your framework expects, such as `OPENAI_API_KEY` and `OPENAI_BASE_URL`. This works in development, staging and production deployments, and any component in the deployment can call `core.diploi`. Tip Do not build the token into a Docker image or commit it to Git. It is unique to each deployment and changes when the deployment is re-enabled. ## Built-in tools Diploi’s own AI tools already use the gateway, so there is nothing to set up for them. In the console, open a development deployment and switch to the **Prompt** view. Describe the change you want, and the agent edits the code for you. OpenCode is set up in every development environment. Run `opencode` in the cloud IDE or in an SSH session. Continue is set up in the cloud IDE with Diploi models selected. Usage from these tools is billed from your balance, the same way as calls from your own app. Note Cursor Chat and Tab run on your own machine, so they cannot reach `core.diploi`. To use Diploi’s models, use Prompt, OpenCode or Continue in the remote environment. ## Supported models Send the model ID exactly as listed. Kimi, GLM and Qwen models use the `/v1` path (see [URL formats](#url-formats)). | Model | Model ID | | ---------------- | ------------------ | | GPT-6 Astra | `gpt-6-astra` | | GPT-6 Sol | `gpt-6-sol` | | GPT-6 Luna | `gpt-6-luna` | | Claude Fable 5.1 | `claude-fable-5-1` | | Claude Opus 5.5 | `claude-opus-5-5` | | Claude Sonnet 5 | `claude-sonnet-5` | | Kimi K2.7 Code | `kimi-k2.7-code` | | GLM 5.3 Flash | `glm-5.3-flash` | | Qwen 3.8-27B | `qwen3.8-27b` | If a request returns `Model … is currently not supported`, check the model ID against this list. ## Billing and limits AI usage is paid from the same prepaid balance as cluster hours, and there is no separate AI subscription. You can see your spending per model on the **Billing** page of your account. On the Trial plan, €1 of AI usage per day is included. The allowance resets at 00:00 UTC, and trial AI usage also uses up your trial credits. To keep going after the daily limit, choose a plan. On Pay as you go, Pro and Ultra, AI usage is billed at model rates from your balance. Pro gets 5% off AI usage and Ultra gets 10% off. When your balance runs out, requests are refused until you add funds. A refused request gets an **HTTP 402** response, with an error that says whether the trial’s daily limit was reached or the balance ran out. Rate limits To keep the gateway reliable for every deployment: * 100 requests per minute for JSON chat and completion calls * 5 requests per minute for multipart uploads (`whisper-1`) * Multipart uploads are limited to 25 MB ## Best practices * Use the `{diploi-ai-gateway-url}` and `{diploi-ai-gateway-token}` placeholders instead of copying values from another deployment. * Call the gateway from server-side code, and never expose the token to browsers or public clients. * Use cheaper models, such as GPT Terra, for high-volume or background jobs. * If your app uses AI all the time in production, keep an eye on the **Billing** page and turn on auto top-up, so the app does not stop when the balance runs out. * If you need a model Diploi does not offer, use your own provider key. Those calls are not billed through Diploi. ## See also * [OpenClaw starter kit](/building/starter-kits/openclaw) * [diploi.yaml Explained](/reference/diploi-yaml) * [Using Remote Development](/building/remote-development) * [Pricing](https://diploi.com/pricing) # Reference › Glossary Source: https://docs.diploi.com/reference/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) ### AI Gateway An OpenAI- and Anthropic-compatible proxy available inside every Diploi deployment at `core.diploi`. Apps and coding tools use it to call supported models without storing provider API keys. Usage is billed from the account balance. *See also:* [AI Gateway](/reference/ai-gateway) ### 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) # Reference › Projects › Projects Explained Source: https://docs.diploi.com/reference/projects/project > 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. ![Selecting a branch to launch a new deployment](/_astro/CreateDeploymentRepository.CiIre1ek_YuRmz.png) By default, when you create a new project, a development deployment will be started, which you can use to start developing your application right away and will be active for 12 hours. This development deployment will use your repository’s default branch main branch as its source. Note If you want to create a new project with a repository, you can do so by following the steps in our [Creating a Project](/deploying/creating-a-project) guide. ### Project Without a Repository When starting a project without a repository, you get a development environment that you can use to test new technologies, simple scripts, cron jobs, or just to try out Diploi without the need to create a repository. Caution When you start a project a without a repository, **you cannot add a repository later**. Which is why we do not recommend it for projects meant for production. Caution **Projects without a repository** are **not intended for production**, as your code will only exist on the deployment launched, and changes will not be persisted to other deployments you launch within the project. You can create a project without a repository by clicking on the “**Launch Without a Repository**” option inside the “GitHub Repository” section, when creating a new project. ![Selection the option to launch a project without a repository](/_astro/CreateProjectWithoutRepo.Csb4Je86_2rqCKP.png) *** If anything was unclear or you need help, talk with us on [Discord](https://discord.gg/vvgQxVjC8G) or [contact us](mailto:hello@diploi.com). # Reference › Projects › Project Lifecycle Source: https://docs.diploi.com/reference/projects/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 [![](https://diploi.b-cdn.net/component/diploi/component-asp/icon.svg?ref=main)**ASP.NET**](/building/components/asp)[![](https://diploi.b-cdn.net/component/diploi/component-astro/icon.svg?ref=main)**Astro**](/building/components/astro)[![](https://diploi.b-cdn.net/component/diploi/component-blazor/icon.svg?ref=main)**Blazor**](/building/components/blazor)[![](https://diploi.b-cdn.net/component/diploi/component-bun/icon.svg?ref=main)**Bun**](/building/components/bun)[![](https://diploi.b-cdn.net/component/diploi/component-deno/icon.svg?ref=main)**Deno**](/building/components/deno)[![](https://diploi.b-cdn.net/component/diploi/component-django/icon.svg?ref=main)**Django**](/building/components/django)[![](https://diploi.b-cdn.net/component/diploi/component-fastapi/icon.svg?ref=main)**FastAPI**](/building/components/fastapi)[![](https://diploi.b-cdn.net/component/diploi/component-flask/icon.svg?ref=main)**Flask**](/building/components/flask)[![](https://diploi.b-cdn.net/component/diploi/component-ghost/icon.svg?ref=main)**Ghost**](/building/components/ghost)[![](https://diploi.b-cdn.net/component/diploi/component-hono/icon.svg?ref=main)**Hono**](/building/components/hono)[![](https://diploi.b-cdn.net/component/diploi/component-laravel/icon.svg?ref=main)**Laravel**](/building/components/laravel)[![](https://diploi.b-cdn.net/component/diploi/component-n8n/icon.svg?ref=main)**n8n**](/building/components/n8n)[![](https://diploi.b-cdn.net/component/diploi/component-nextjs/icon.svg?ref=main)**Next.js**](/building/components/next)[![](https://diploi.b-cdn.net/component/diploi/component-nodejs/icon.svg?ref=main)**Node.js**](/building/components/node)[![](https://diploi.b-cdn.net/component/diploi/component-python/icon.svg?ref=main)**Python**](/building/components/python)[![](https://diploi.b-cdn.net/component/diploi/component-react-vite/icon.svg?ref=main)**React + Vite**](/building/components/react-vite)[![](https://diploi.b-cdn.net/component/diploi/component-static/icon.svg?ref=main)**Static Website**](/building/components/static)[![](https://diploi.b-cdn.net/component/diploi/component-supabase/icon.svg?ref=main)**Supabase**](/building/components/supabase)[![](https://diploi.b-cdn.net/component/diploi/component-sveltekit/icon.svg?ref=main)**SvelteKit**](/building/components/sveltekit)[![](https://diploi.b-cdn.net/component/diploi/component-tanstack-start/icon.svg?ref=main)**TanStack Start**](/building/components/tanstack-start) ### 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 [![](https://diploi.b-cdn.net/component/diploi/addon-mariadb/icon.svg?ref=main)**MariaDB**](/building/add-ons/mariadb)[![](https://diploi.b-cdn.net/component/diploi/addon-minio/icon.svg?ref=main)**MinIO**](/building/add-ons/minio)[![](https://diploi.b-cdn.net/component/diploi/addon-mongo/icon.svg?ref=main)**MongoDB**](/building/add-ons/mongo)[![](https://diploi.b-cdn.net/component/diploi/addon-postgres/icon.svg?ref=main)**PostgreSQL**](/building/add-ons/postgres)[![](https://diploi.b-cdn.net/component/diploi/addon-redis/icon.svg?ref=main)**Redis**](/building/add-ons/redis) Note Services are not exposed publicly by default. They can only be accessed by the components in your project. *** ### Previewing your Project In this section, you can see a preview of your monorepo folder structure at root level. ![Create project preview](/_astro/CreateProjectPreview.Dib1Ltua_21J97h.png) Note From the preview, you can rename the folders that contain your components and the add-on names that your application will be using, by clicking on the element you want to edit ![Edit component or add-on name](/_astro/CreateProjectEditNames.CB7Lv93s_XxGW4.png) ### Choosing Between Creating a Project with or without a Repository A **Project with a repository** is the default way to set up a project, Diploi bootstraps a new GitHub repository for you and generates a scaffold for your app based on the Stack you choose. additionally Diploi creates a CI/CD pipeline so changes can be persisted across multiple environments and allows your project to be launch in Staging and Production. A **Project without a repository** used when you want to test a Stack or you want to run a simple scripts and apps online without a repository. Caution Once you choose between using a new repository or launching without a repository, you will not be able to change the repository or add a repository. Note **Using an existing repository and importing an application to Diploi** is not yet an automagically process, but it is possible. If you would like to bring your existing application to Diploi, contact us on [Discord](https://discord.gg/vvgQxVjC8G) or [via email](mailto:hello@diploi.com). For more information about how to use the Import from GitHub feature, [check this article](/deploying/import-from-github). *** ## Managing a Project After creating a project, you will be able to create new deployments and modify the options of the project. ![Project home page](/_astro/ProjectHomePage.uws8997t_ZrUtAR.png) ### 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. ![Project options general](/_astro/ProjectOptionsGeneral.CddUg5uG_ZcvxtK.png) Note If you update the name of your project, it won’t affect the repository’s name. #### Parent Domain By default, Diploi generates a domain for your application. The basic structure of a generated domain uses the following logic: ```plaintext ..diploi.app ``` ![Project options parent domain](/_astro/ProjectOptionsDomain.BP4iVfxG_Z25RT88.png) Tip If you want to set up a custom domain, you can do it from each deployment. For more information, click here [Deploying / custom-domain](/deploying/custom-domain/) ## Deleting a Project When you no longer need a Project you can delete it by first deleting all deployments within the project and the going to the “options” tab of your projects and look for the actions sections, to delete the project click on the “delete project” button. ![Delete project](/_astro/DeleteProject.DVT4vwtr_2kBVHu.png) # Reference › Deployments › Deployments Explained Source: https://docs.diploi.com/reference/deployments/deployment > 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. # Reference › Deployments › Deployment Lifecycle Source: https://docs.diploi.com/reference/deployments/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 general settings](/_astro/CreateDeploymentGeneral.9v50FIi2_NOg93.png) Note The stage for your deployment will define if your environment is a dynamic or a build deployment. #### Deployment Name This will identify the internal name of your deployment within your Diploi project. You can change the name of a deployment at any time. Changes to the project name will not affect your deployment, project, repository or dependencies. #### Deployment Stage In Diploi, you have three stages that you can assign to your deployments: ##### Development Development deployments enable remote development and let your application be served online development. It offers a cloud IDE that can be used for remote development and also allows you to SSH into the environment using VSCode. Development deployments often utilize hot module reloading (HMR) or similar techniques to enable quick code updates without server restarts. When using this stage, your code is cloned directly from GitHub without going through the build process. ##### Staging Staging deployments are used for testing and quality assurance purposes. They run a build version of your application, exactly as your Production deployments do but as an independent deployment that would not affect your Production deployment. ##### Production Production deployments host the build version of your application and it is intended to be the version of your application that your users will have access to. ### Size You must choose the appropriate size for your application. You can update the size of your deployment directly from the Options tab of your deployment. \- **XS** - 2 vCPUs and 2 GB of ram - **0,006 €/hour** \- **S** - 2 vCPUs and 4 GB of ram - **0,014 €/hour** \- **M** - 2 vCPUs and 8 GB of ram - **0,048 €/hour** \- **L** - 4 vCPUs and 16 GB of ram - **0,089 €/hour** \- **XL** - 8 vCPUs and 32 GB of ram - **0,182 €/hour** ### Repository In this section, you will be able to define the branch that your deployment will use. You can change the branch source for your deployment from the **Repository & Git** tab of your deployment. ![Deployment repository branch](/_astro/CreateDeploymentRepository.CiIre1ek_YuRmz.png) Note The Repository section is only available for projects that are started with a repository. ### Component and Add-on Settings Depending on your project’s components and add-ons, you might be able to make changes to the configuration, changes in this section will not affect other deployments or your project’s default configuration. ![Project options components and add-ons](/_astro/ProjectOptionsComponentsAndAddons.BYd3ACvc_242WsQ.png) Note Not all components and add-ons have editable settings in this section. ## Cloning a Deployment To duplicate an existing deployment (including its database and configuration), open the deployment dashboard, go to the **Options** tab, and scroll to the bottom. `https://console.diploi.com//project//deployment//options` There, look for the section “Clone Deployment” and click on the “Clone this deployment” button. This will open the cloning wizard, which follows [the same workflow as when you create a new deployment, explained in the previous section](#creating-a-deployment). ## Managing a Deployment Once you have created a deployment inside a project, you can access your deployment’s settings from the project page. ![Deployment home page](/_astro/DeploymentHomePage.-kvugADD_Zofuju.png) Note Depending on the deployment stage of your deployment, the overview page will show different information. **For Development deployments**, the overview will show an additional entry **Development**, which allows you to access the remote development environment using our cloud IDE or VS code. ### Overview From the overview tab, you can see the status of your deployment, view the logs for each component and add-on running and resources used. The overview tab is divided in three core sections: #### Develop Section Only available on Development deployments In this section, you can get the SSH connection string to your development environment and access to the remote IDE environment. ![Add IDE to deployment](/_astro/DevelopmentLocalIde.D3nySK3z_g9xoH.png) Note For deployments that are not for development, you can still access the deployment with SSH [by going to the containers section in the overview page](#connect). ##### Remote Development Diploi supports remote development by using the remote development capabilities of eg. Visual Studio Code, but any editor that supports editing using an SSH connection will work. For more details, please see the [Remote Development](/building/remote-development/) guide. ##### Connecting using SSH Once you have created a deployment, look for the “Connect via SSH” command on the “Overview” tab. This command can be copied to your terminal of choice to open an SSH connection to the deployment. Note You will need to add an SSH key to your profile in order to authenticate via SSH. Please see the [Add SSH Key](/building/add-ssh-key/) guide for more information. *** #### Status tree Where you can see the resources your deployment is using and the status of containers that are part of your deployment, logs, SSH connections for each container and their endpoints of all components and add-ons available on your application. ![Status and resources view](/_astro/StatusTree.DMr4B8KQ_Q5Y5F.png) All public facing URL endpoints that your applications expose have SSL encryption by default. Note All add-ons by default are only accesible locally by your applications and are not exposed to the wider internet. #### Deployment Component and Add-on Status In this section you can visualize the status of each component and add-on that defines your deployment. ![Component and Add-on pods status](/_astro/PodStatus.biLgCW0h_bUePf.png) ##### 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 ![Pod status highlighted](/_astro/PodStatusHighlight.DPvRxsGj_Zoz2h7.png) * **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. ![Pod logs action](/_astro/PodLogs.DHimb-4C_Z1RSP8v.png) 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. ![Container logs](/_astro/ContainerLog.BySA9AoJ_dI5xw.png) ##### Restart This action allows you to restart an individual component or add-on, without affecting the configuration of your deployment and other running components. ![Pod restart action](/_astro/PodRestart.CGOJmJUo_ZTnCPX.png) ##### 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. ![Conntect to container](/_astro/CreateDeploymentConnect.BMKmN1OH_ZUH01k.png) Note To connect via SSH to any deployment, you first need to [add your public SSH key to Diploi](/building/add-ssh-key). ##### Describe In some situations where you need to view how your components and add-ons are actually being implemented and started by Diploi, you can use the **Describe** feature to review the Kubernetes config of a particular component in your deployment. ![Pod describe action](/_astro/PodDescribe.BrE4tgnv_QcQ59.png) This will also show additional information, such as debug messages and pod specs, which could be used for debugging and support requests. ![Pod describe dialog](/_astro/PodDescribeOpen.BJjgL8zd_ZzNfv3.png) *** #### Deployment resources Here you can view how your application is using the resources available to the deployment. ![Stack preview and logs](/_astro/ResourceView.IqzoM26N_Zn6okY.png) 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 repository settings](/_astro/DeploymentRepoSettings.DpeHjskp_2dKooa.png) ### 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. ![Project options general](/_astro/DeploymentOptionName.D25EWmMG_1Lcdqw.png) Note If you update the name of your deployment, it won’t affect the repository’s name or alter your application’s behavior. #### Machine Size You can change the size of the deployment machine that your deployment uses, by first disabling the deployment and then choosing a different size. ![Project options size](/_astro/DeploymentOptionSize.B71qS9GD_1mVMdk.png) #### 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/). ![Deployment endpoints](/_astro/DeploymentOptionEndpoints.xLXv-F-w_ASHL7.png) ##### 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: ![Godaddy domain example](/_astro/GodaddyCustomDomainExample.DopYJ9t6_14rpvi.png) Note When you first assign a new domain for your application, it can take up to 30 minutes for the new SSL certificate to become valid. #### Managing Environment Variables You can customize the environment variables that each of your components and add-ons use. Some variables are automatically generated from your add-ons into your components. ![Deployment environment](/_astro/DeploymentOptionEnvironment.CFG4zwcG_xcT1p.png) ## 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. ![Delete deployment](/_astro/DeploymentOptionDelete.Dm0sNFe2_Z11r8Qf.png) Note If you want to delete an entire project, you must first delete all deployments that belong to the project first. # FAQ Source: https://docs.diploi.com/faq > Frequently asked questions about Diploi ## Getting Started **Can I use Diploi for production applications?** Yes! Diploi supports production deployments with proper resource allocation, custom domains, and SSL certificates. We provide enterprise-grade infrastructure suitable for production workloads. However, our single-node kubernetes version does not scale infinitely so to support very busy sites Diploi might not yet be the perfect solution. We are hard at work on a more scalable version. See the [roadmap](/roadmap/) for more details. **How much does Diploi cost?** Check our [pricing page](https://diploi.com/pricing) for current pricing information. We offer different tiers to suit various needs, including 100% free trial of the full Diploi experience. Generally speaking Diploi is very affordable when used for development (4€/deployment/month and upward), since you only run the clusters while you are working. A typical production cluster starts from around 20€/month, when you consider that the same cluster can run both your frontend, backend and database we think it can be considered very affordable. **Do I need a GitHub account?** Yes, Diploi requires GitHub integration because it creates repositories for your projects and handles CI/CD builds through GitHub actions. This ensures version control and seamless collaboration. **Can I try Diploi without registering?** Yes! You can use launch a trial without registration. Visit [diploi.com/#StackBuilder](https://diploi.com/#StackBuilder) to start a deployment in seconds. Deployments launched without registration expire after 12 hours but you can claim the account and continue working. ## Features & Capabilities **What frameworks and databases are supported?** See our [components documentation](/building/components/) for a complete list of supported frameworks and databases. We support popular technologies like React, Next.js, Node.js, Python, PostgreSQL, MongoDB, and many more. **Can I migrate an existing project to Diploi?** While Diploi is optimized for new projects, you can import existing projects into diploi. Currently we have decent support for Node and Lovable projects, but we are hard at work at improving this. **Can I use custom domains?** Yes, Diploi supports custom domains with automatic SSL certificate management. See our [custom domain guide](/deploying/custom-domain/) for setup instructions. **How do I update my application?** For projects with repositories, simply push changes to your connected branch. Diploi will automatically rebuild and redeploy your application to the deployments following that branch. It will also consider changes in infrastructure by looking at `Diploi.yaml` Please note that development deployments will only update in part, because you maintain the code part through the editor. **Can I have multiple environments?** Yes! You can create development, staging, and production deployments for the same project, each with different configurations and resource allocations. **What happens if I exceed my limits?** You’ll be notified before reaching limits. Some features may be temporarily restricted until you upgrade or reduce usage. Check your dashboard for current usage statistics. **How do I call AI models from my app?** Use the [AI Gateway](/reference/ai-gateway). Inject `{diploi-ai-gateway-url}` and `{diploi-ai-gateway-token}` into your component and point an OpenAI- or Anthropic-compatible client at it. You do not need your own provider API keys. The cloud IDE, OpenCode, and the Prompt view already use this gateway. **How is AI usage billed?** AI is metered from the same prepaid balance as your deployments. Trial accounts include €1 of AI usage per UTC day. Paid plans are billed at model rates, with 5% off on Pro and 10% off on Ultra. See [pricing](https://diploi.com/pricing) and the Billing page in the console. **Can I use the AI Gateway from my laptop?** No. The gateway is only reachable inside the deployment containers, at `core.diploi`. Use Prompt in the console, OpenCode or Continue in the remote environment, or call it from your deployed app. ## Pricing & Plans **Is there a free tier?** Yes, we offer free development deployments with basic resources. These are perfect for testing and learning. **How does billing work?** Billing is based on resource usage and deployment duration. You only pay for what you use, with transparent pricing. **Can I cancel anytime?** Yes, you can cancel your subscription at any time. Your deployments will stop running if you cancel your subscription. ## Security & Data **Is my data secure?** Diploi follows industry best practices for security, including: * Encrypted data transmission (HTTPS/TLS) * Secure infrastructure with regular security updates * Isolated deployments Currently you are required to take care of backups of your data yourself. We can provide regular backups of your data upon request, we are working on adding configuration options for this feature. **Can I export my data?** Yes, you can export your data and configurations. Contact support for assistance with data export. **Where is my data stored?** Your data is stored in AWS datacenters, Ireland, Europe. We are working on multiregion support. **Do you have compliance certifications?** We’re working on obtaining relevant compliance certifications. Contact us for specific compliance requirements. ## Technical Questions **What’s the difference between components and add-ons?** * **Components**: Application layers (frontend, backend, full-stack) that users can access * **Add-ons**: Services (databases, cache, etc.) that are only accessible to your components **How does the deployment process work?** 1. You create a project with your chosen stack 2. Diploi creates a GitHub repository with starter code 3. You can edit code via cloud IDE or locally 4. Changes are automatically deployed when you push to GitHub **Can I use my own Docker images?** Currently, we use pre-configured components, but the Dockerfile for running them is included in your project, so feel free to modify them as you wish, However different component have different requirements to work well. **What ports does my application need to listen on?** Most applications should listen on port 3000 or 8080. Check the specific component documentation for exact requirements. ## Support & Community **How can I get help?** * **Discord**: Join our [Discord community](https://discord.gg/vvgQxVjC8G) * **Email**: Contact us at * **GitHub**: Open an issue in our [documentation repository](https://github.com/diploi/docs) **Do you offer priority support?** Yes, priority support is available for enterprise customers. Contact our sales team for more information. **Can I request new features?** Absolutely! We love hearing from our community: * Share ideas on [Discord](https://discord.gg/vvgQxVjC8G) * Email suggestions to * Open issues on [GitHub](https://github.com/diploi/docs) ## Still Have Questions? If you didn’t find the answer you’re looking for: * **Join our [Discord community](https://discord.gg/vvgQxVjC8G)** for real-time help * **Contact us directly** at We’re here to help and always appreciate feedback on how we can improve our documentation! # Troubleshooting Source: https://docs.diploi.com/troubleshooting > Quick fixes and deep-dive guides for common Diploi issues (remote dev, Git, deployments, domains, add-ons). Find the case that matches your situation and follow the checklist. Each section ends with what to collect if you need support. ## Start here * **New issue and you’re not sure where to look?** Start with **[First-aid checklist](#first-aid-checklist)** * **Imported app fails to run?** Go to **[Hosting existing apps from GitHub](#hosting-existing-apps-from-github)** * **Can’t connect to your environment?** Go to **[SSH and Remote Development](#ssh-and-remote-development)** * **Git push/pull/auth problems?** Go to **[Git and GitHub](#git-and-github-issues)** * **Build failed / deploy stuck / wrong version running?** Go to **[Builds and Deployments](#builds-and-deployments)** * **Domain or SSL issues?** Go to **[Custom domains & SSL](#custom-domains-and-ssl)** * **Database/add-on connection errors?** Go to **[Databases & add-ons](#databases-and-add-ons)** * **Slow app / OOM / resource limits?** Go to **[Performance & limits](#performance-and-limits)** * **Other issues not listed in this guide?** Go to **[Getting Help](#getting-help)** Good to know Most issues are commonly caused by runtime errors, which can be found by checking the deployment’s **logs** from the Overview tab. *** ## First-aid checklist The fastest path from “something is broken” to a clear root cause. Try these steps first. They solve most issues in minutes. ### 1. Identify the deployment stage * **Development**: meant for remote development (Cloud IDE / VS Code / Cursor / Zed), code is editable live. * **Staging/Production**: runs a built image (CI/CD style), code changes come from a Git branch, and updates when you push updates to said branch. ![Deployment Stage](/_astro/DeploymentStage.BJqYqfYU_1QFec2.png) ### 2. Check status and logs * Open the deployment **Overview** * Look for: * Failing containers/services * Recent restarts * Error lines in the logs of a component * Deployment status shows “possible issues” or an error state From the development environment, the same in three commands with [the Diploi CLI](/reference/diploi-cli): ```bash diploi status # what is running, and what needs attention diploi logs diploi events -w # warnings from Kubernetes: failed pulls, crashes, failed probes ``` ### 3. Confirm what changed * A new dependency? * A change to `diploi.yaml`? * A DNS or domain change? * A framework upgrade? ### 4. Try the smallest rollback * Revert the last change (code or config) * Restart the affected service/deployment * Stop and start the deployment again * If you updated a domain or DNS settings, you need to wait up to 30 minutes for the changes to propagate *** For more specific issues, refer to the cases listed below. In case none of the listed categories fit your situation, check the section showing how [to get help for other issues](#getting-help) and contact our team. *** ## How this guide is structured Each troubleshooting section follows the same pattern: 1. **Symptoms** (what you see) 2. **Fast fixes** (5-10 minutes) 3. **Deep diagnosis** 4. **If still stuck (collect this)**: a copy/paste checklist for support *** ## Hosting existing apps from GitHub Diploi’s automated import feature tries to configure any app you import, but it is not fail-proof. These are some common situations you might find, and how to handle them. ### Symptoms * Import analysis determined that the app could be hosted on Diploi, but the app shows a 502 error or fails to load * Import failed, but the app has a `diploi.yaml` file already or it was created using Diploi * Import analysis finished successfully for a fullstack app, but one of the components fails to start ### Fast fixes #### Reset your deployment Sometimes, the resource allocation API might fail during the startup of your app, which can cause your app to get stuck while trying to start. Try disabling the deployment and enabling it again to run the startup sequence again. ![Disabling a deployment](/_astro/DisableDeploymentSwitch.Bf_4-l1j_22lyVQ.png) #### Failing components or deployment fails to start In cases when you have a multi-component app, it could be the case that a one of the components fails to start. This could be because ENV variables are missing or there are version conflicts. Check the [builds and deployments](#builds-and-deployments) section which goes over what to do. #### Missing components or add-ons If your app’s stack was not correctly detected, you can manually configure the mising elements by editing the `diploi.yaml` file in the root of your project. For more information about how to use the `diploi.yaml` file, check [this article explaining how to use it](/reference/diploi-yaml). ### Deep diagnosis #### Review deployment logs In most situations, when your import fails to start, it is possible that the import system used the wrong start commands or some files are missing in your repository. To debug these situation, you can view the logs of each component in your app to determine why your app might be failing to start. ![Viewing deployment logs](/_astro/PodLogs.DHimb-4C_Z1RSP8v.png) ### If still stuck (collect this) * List the components of your app’s stack, eg. Next.js + Deno + Redis + Mongo * Your deployment’s URL, eg. `https://console.diploi.com//project//deployment/` * Describe the issue(s) you found while trying to host an app *** ## SSH and Remote Development For issues related to remote access via SSH to development environments or app containers, via Cloud IDE, VS Code, Cursor, Zed, or from a terminal. ### Symptoms * VS Code/Cursor/Zed can’t connect (timeout, permission denied, handshake failed) * SSH prompts keep repeating when you try to connect with your local IDE * Cloud IDE works, but local IDE does not * Connection fails when trying to access a container with SSH ### Fast fixes #### Confirm your SSH key is added Follow the SSH key guide and re-check that you pasted the **public** key (the `.pub` content).\ See: [Connecting via SSH](/building/add-ssh-key/) #### Try connecting using SSH from the terminal From the deployment Overview, copy the **Connect via SSH** command and run it locally. ![Connecting to a development environment via SSH](/_astro/DevelopSectionCopySSH.ClvncBJJ_27JOPI.png) Then use the copied SSH connection string from your terminal, eg, `ssh dev-z8E49384c728@console.diploi.com` * If this fails, when you try connecting from your local IDE, it will also fail. * If this succeeds, the issue is usually local IDE configuration or possibly because your SSH private key has not been added to the SSH agent. #### Windows and WSL If you use Windows with WSL, verify which environment your IDE is using for SSH keys, Windows user, or WSL user. ### Deep diagnosis #### Host key / known\_hosts conflicts If you see messages about a host key changing, remove the old entry from your `~/.ssh/known_hosts` (or use `ssh-keygen -R `), then reconnect. #### Permissions Ensure: * `~/.ssh` has read/write/execute permissions, using the command `chmod 700 ~/.ssh` * Private and public keys must have read/write permissions, using the command `chmod 600 /` for the key pair used. ### If still stuck (collect this) * Exact SSH command you ran * Full terminal output (redact secrets) * Your OS and IDE (VS Code/Cursor) version * Whether Cloud IDE works * [Contact us](#where-to-ask) *** ## Git and GitHub issues For issues related to GitHub auth, push/pull failures, and repository access problems in Diploi deployments. ### Symptoms * `fatal: Authentication failed` * `remote: Permission to denied` * The production and Staging environments fail to update ### Fast fixes #### 1. Retry running the git command In some situations, when you try to run a git command, eg, `git pull`, the first try might fail due to connection issues or latency, but in most cases, trying to run the command again can clear the issue. #### 2. Verify that Diploi still has access to the repository If you recently modified Diploi’s access to your repositories, it is possible that the project you are using is no longer in sync with GitHub, which would prevent you from pushing or pulling. To restore access, visit and check if Diploi is still installed in the repository linked to your Diploi project. #### 3. Check that the GitHub actions succeed after pushing an update For situations when your Staging or Production environments show a version of your application which is not the latest, check that the branch where you pushed your updates has run an action and is marked as successful. ![GitHub Action results](/_astro/GithubActionResults.B7PMoweS_Z2dWO8c.png) Diploi uses GitHub Actions to create builds of your application for Development and for Staging/Production. ### Deep diagnosis #### Your project was initiated without a repository If you started a project without a repository, and you use git init or clone a repository inside the repository, then any authentication you add to sync with GitHub won’t be managed by Diploi, so if you create new deployments, you’ll need to manually authenticate in GitHub in order to sync your code. ### If still stuck (collect this) * The command you ran (`git fetch`, `git push`, etc.) * The exact error output * Whether this is a Development deployment or a Staging/Production stage * Whether the deployment has an assigned user * [Contact us](#where-to-ask) *** ## Builds and Deployments Troubleshoot failed builds, stuck rollouts, wrong version running, and unhealthy services. ### Symptoms * Deployment stuck on “starting” / “Initializing” / “Possible issues” / “Error” * App is up, but is not showing the latest commit * One component/add-on fails to run or restarts constantly * Staging/production doesn’t reflect `diploi.yaml` changes ### Fast fixes #### 1. Confirm deployment type * Development deployments are optimized for remote dev * Staging/Production deployments run a built image #### 2. Check the deployment status tree and service logs Inspect the failing components/add-ons and check their logs, looking for errors. If the components and add-ons seem to be working correctly, but your application still shows errors, open the live view of each component with the browser Developer Tools open. Check the console and network tabs to find any potential issues preventing your application from running. #### 3. Verify that the ports used in your application config match the Dockerfile settings If you configured the ports used by a component or add-on in your application, make sure to update them inside the `Dockerfile` (for Staging/Production) and the `Dockerfile.dev` (for Development environments). #### 4. Verify your CI/CD run If your project’s GitHub Action didn’t run or at least one of the builds failed, the deployment will remain on the last build where all components were successful. You can find the issues with your GitHub Actions by reviewing the execution logs of the action. ### Deep diagnosis #### Config changes (`diploi.yaml`) not taking effect * Confirm that the `diploi.yaml` file is in the repo and committed * Confirm that the change is on the branch tied to the deployment * Make sure to apply any changes from your `diploi.yaml` file to your deployment, and then push the changes to your repository ![Confirming changes to Deployments](/_astro/ConfirmingChangesToDeployment.D1PnzoVd_iOPSS.png) #### Other common failure patterns ##### GitHub Action build fails * Check the GitHub Action’s workflow run logs * Make sure that dependency changes are part of the lockfiles of your components, eg, for Python `uv.lock`, for JS `package-lock.json` ![Build fails](/_astro/GithubActionFails.B83s0mUI_Z1UQiLX.png) ##### Build succeeds, but runtime fails * Make sure that all necessary ENV variables are defined * If your components require add-ons to operate, make sure to run the necessary migrations and that the add-ons are reachable * If you made changes to a component and now use a different run command, update it inside the `Dockerfile` and `Dockerfile.dev` belonging to the component ### If still stuck (collect this) * Deployment stage and name * Link to the CI run (if it’s a public repository) * Logs from the failing service (include startup section) * What changed (code/config/add-ons) * [Contact us](#where-to-ask) *** ## Custom domains and SSL For issues linked to DNS records, propagation, and SSL provisioning issues for custom and Diploi domains. ### Symptoms * After changing a deployment’s domain, the app fails to render * DNS works for `www` but not apex/root * SSL pending or browser certificate warning * Domain verified in one place (DNS) but not in Diploi ### Fast fixes #### 1. Verify the record type and target * Subdomain usually uses a **CNAME** pointing to `edge.diploi.me` * Ensure the **name/host** matches the subdomain you intended #### 2. Wait for DNS propagation Use your DNS provider UI to confirm the change is saved and active. Changes to DNS records can take up to 30 minutes to propagate. #### 3. Apex/root domains Some providers need ALIAS/ANAME-style records for apex domains. Make sure to assign the right record type. For more information about record types, check our article listing the types of records supported based on the provider you use: [Configuring a custom root domain](/deploying/custom-domain#configuring-a-custom-root-domain). #### 4. Verify your application’s endpoints are not hardcoded or defaulting to use http If you use hardcoded endpoints within your application, remember to update them to match your new domain, and verify that they use https by default. In Diploi, both custom and autogenerated domains are SSL-protected by default. Note If your provider only supports A records at the root, document what you tried and contact us. ### Deep diagnosis #### Wrong environment bound to the domain Diploi supports domains at both project and deployment levels. Verify you added it to the intended level. ### If still stuck (collect this) * Domain name and record screenshots * Which DNS provider do you use * Whether it’s project-level or deployment-level domain * Timestamp when you updated DNS *** ## Databases and add-ons Fixing connection issues, missing env vars, and common configuration mistakes with add-ons like Postgres/Redis/Mongo/MariaDB/MinIO. ### Symptoms * “Connection refused” * “password authentication failed” * App starts, but features using the DB fail * Works in dev, fails in staging/prod (or vice versa) ### Fast fixes #### 1. Confirm the add-on is running and healthy Check the deployment Overview status tree and the add-on logs. ![Healthy add-on example](/_astro/HealthyAddonExample.hm1761PR_ZVu5kh.png) #### 2. Confirm if your app imports env variables from the deployment or from a .env file If your application is using both an `.env` file and the environment variables of the deployment, your application might have conflicting duplicate variable declarations. Make sure to only use one source for your environment variables. We recommend that you keep your variables declared with the deployment environment variables. ![Deployment environment variables](/_astro/DeploymentEnvVars.BZ4gR8uC_Z26Elrp.png) #### 3. Trying to connect to an Add-on from a service or API outside of your deployment Add-ons hosted on Diploi are not accessible to services outside of the deployment they belong to. If you want to make data accessible to external services, you need to create a broker service that would handle requests on behalf of the add-on you want to access. ### Deep diagnosis #### Migrations/schema init If the DB is reachable but your app still errors, check whether migrations ran and whether they’re expected to run during startup. ### If still stuck (collect this) * Add-on type and identifier * Failing error message and stack trace * Add-on logs around startup * [Contact us](#where-to-ask) *** ## Performance and limits Issues related to slow apps, out-of-memory(OOM) states, and deployment crashes due to high resource load and usage. ### Symptoms * Slow responses/timeouts * Container shuts down/OOM/crash loops under load * Deploy show state as “running” but none of the container logs are visible and endpoints fail to load * Works in Development but not Production ### Fast fixes #### 1. Check resource graphs and container restarts Look for spikes, sustained high usage, or repeated restarts. ![Deployment using resources heavily](/_astro/HeavyUtilization.CC2GupHs_C1uoB.png) #### 2. Increase deployment size or split into multiple deployments In situations where you are running heavy workloads or running many components/add-ons in one deployment, the resource needs of the deployment can rise and cause Kubernetes to kill all containers in the deployment. Try increasing the size of the cluster that your deployment uses or splitting your application into multiple projects. ![Updating the size of a deployment](/_astro/CreateDeploymentSize.Dfgzs_1Q_Z1FkIfw.png) #### 3. API connections break due to 504 Gateway Timeout, proxy timeout, or idle timeout **Diploi has a connection length limit per request/response processed by a service of 60 seconds**. If a request takes more than 60 seconds to be handled, the connection will be terminated, and your process waiting for a response will fail. In cases when a request could take longer than 60 seconds, we recommend you add pooling or a webhook to send the response to a request when the service is ready. ### Deep diagnosis #### Performance issues during cold starts or while running If your deployment is slow during start-up only, it could be due to the size of the build image and might not affect the actual running performance of your application. This is common for deployments with n8n, Supabase, and/or Ghost components, which can consume a large share of resources during startup, compared with other of our supported components. #### Performance issues during cold starts or while running If your deployment experiences slow performance exclusively during cold starts, it is usually due to the containerization process and **cannot be significantly improved**. This **does not impact the actual running performance** of your application once initialized. You might notice this with resource-intensive components like n8n, Supabase, or Ghost during startup. For cases when runtime performance is the issue, try optimizing your application’s architecture: * Use database indexes and caching strategies * Minimize synchronous operations during request handling * Check if third-party services are causing bottlenecks The main point to note is that cold-start delays might be unavoidable for some components, while runtime performance is directly influenced by your application’s design and configuration. ### If still stuck (collect this) * Average traffic volume * CPU/RAM utilization * Logs from the components and/or add-ons where timeouts and out-of-memory events happened * [Contact us](#where-to-ask) *** ## Getting help In case your situation is not included in the listed issues above, or this guide is not enough to handle the issue you encountered, here we list some general information you can share with us to handle your support request faster. ### Before you reach out Make sure you’ve done: * [First-aid checklist](#first-aid-checklist) * Collected logs and exact error(s) text * Include any additional details which are relevant to your issue ### What to include * Project ID * console.diploi.com/*USERNAME*/project/**PROJECT\_ID** * Deployment ID * console.diploi.com/*USERNAME*/project/*PROJECT\_ID*/deployment/**DEPLOYMENT\_ID** * Description of the issue and expected behavior * Steps to reproduce the issue * Logs (20-50 lines) showing the errors triggered * Your Diploi username or GitHub account ### Where to ask You can contact us directly via email or by messaging us in our [Discord community](https://discord.com/invite/vvgQxVjC8G) # Roadmap Source: https://docs.diploi.com/roadmap > Feature roadmap and upcoming improvements for Diploi Here is a short list with item we are currently working on. ### Improved project import Basic support for importing and running existing GitHub repositories was recently added. We now support **Lovable** and some basic **NodeJS** projects. The idea is to gradually expand this support to be able to run as many types of tech stacks as possible, preferably without any configuration. Expect improvements on a monthly basis. Just running any kind of existing repository is a little more tricky for us than eg. Railway or Netlify since we also need to run the system in development preferrably with hot-reloading and all other development specialties working. ### Custom components Custom components will allow power users to create and fine-tune their own components in order to run technologies not currently supported by Diploi. Dipli components and add-ons are based on Helm charts, so this will provide a lot of flexibility. Note **Interested in early access?** If you need this capability now, we might be able to make special arrangements. Please contact us at . ### Inline components We intend to make it possible to include a component’s configuration directly in your source repository, allowing for tight control on exactly how the cluster is configured. This will also be useful for component editors. ### Vertical scaling This will make it possible to use Diploi for applications with more traffic than a single-node cluster can handle, it will also improve availability and reliability. ### Community Requests We’re tracking feature requests from our community. Here are the most requested features: 1. **Multi-language support** - Support for more programming languages 2. **Database migrations** - Automated database schema management 3. **CI/CD integration** - Built-in testing and deployment pipelines 4. **Team management** - Advanced collaboration features 5. **Monitoring & Analytics** - Built-in application monitoring ### How to Request Features Have an idea for a new feature? We’d love to hear from you: * **Discord**: Join our [Discord community](https://discord.gg/vvgQxVjC8G) and share your ideas * **Email**: Send us your suggestions at * **GitHub**: Open an issue in our [documentation repository](https://github.com/diploi/docs) ### Stay Updated To stay informed about new features and updates: * Follow us on [GitHub](https://github.com/diploi) * Join our [Discord community](https://discord.gg/vvgQxVjC8G) * Subscribe to our newsletter * Check our [blog](https://diploi.com/blog) for announcements *** Tip **Have feedback on our roadmap?** We’re always looking to improve our planning and would love to hear your thoughts on our priorities and timeline.