# How to Create Apps in App Platform

App Platform is a fully managed Platform-as-a-Service (PaaS) that deploys applications from Git repositories or container images. It automatically builds, deploys, and scales components while handling all underlying infrastructure.

App Platform retrieves your app’s code from your linked repository or container registry, detects the type of language the app is written in, and deploys the app into an appropriate container environment. App Platform hosts the app at a public URL provided by DigitalOcean and can automatically redeploy the app when it detects changes in the repo.

App Platform supports deployment from the following source code management services:

- GitHub
- GitLab
- Bitbucket
- [DOCR](https://docs.digitalocean.com/products/container-registry/index.html.md)
- Docker Hub
- GitHub Container Registry

Creating an App Platform app involves two steps:

1. Choose a deployment source.
2. Review and configure resource settings (such as the app’s name, region, size, instance type, instance sizes, environment variables, and HTTP routes).

Apps include two types of deployable resources: app resources for running code, and database resources for managed databases.

App resources are made up of [components](https://docs.digitalocean.com/products/app-platform/details/intro-faq/index.html.md#what-are-components-in-app-platform), which define how code is built, deployed, and run. Supported component types include web services, static sites, workers, and jobs. Web services, workers, and jobs run in containers from a repository or container image, while static sites are hosted from a directory of static files on DigitalOcean’s CDN.

You can change the configuration and add more services, static sites, and databases after you create the app.

**Note**: You must have an [**Owner** or **Maintainer** permissions-role](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) in any GitHub repository that you want to access from App Platform.

## Create an App Using Automation

To create an app using the CLI or API, provide a path to an [app spec file](https://docs.digitalocean.com/products/app-platform/reference/app-spec/index.html.md) (JSON or YAML) as the argument for the `--spec` flag using the CLI, or provide a spec as a JSON object in the `spec` field of the App Create API request.

## How to Create an App Using the DigitalOcean CLI

1. [Install `doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md), the official DigitalOcean CLI.
2. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with `doctl`.
3. Use the token to grant `doctl` access to your DigitalOcean account.

   ```shell
   doctl auth init
   ```
4. Finally, run `doctl apps create`. Basic usage looks like this, but you can [read the usage docs](https://docs.digitalocean.com/reference/doctl/reference/apps/create/index.html.md) for more details:

   ```shell
   doctl apps create [flags]
   ```

   The following example creates an app in a project named `example-project` using an app spec located in a directory called `/src/your-app.yaml`. Additionally, the command returns the new app’s ID, ingress information, and creation date:

   ```shell
   doctl apps create --spec src/your-app.yaml --format ID,DefaultIngress,Created
   ```

## How to Create an App Using the DigitalOcean API

1. [Create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) and save it for use with the API.
2. Send a POST request to [`https://api.digitalocean.com/v2/apps`](https://docs.digitalocean.com/reference/api/digitalocean//index.html.md#operation/apps_create).

### cURL

Using cURL:

```shell
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps"
  -d '{"spec":{"name":"web-app","region":"nyc", \
  "services":[{"name":"api","github":{"branch":"main",\
  "deploy_on_push":true,"repo":"digitalocean/sample-golang"}, \
  "run_command":"bin/api","environment_slug":"node-js", \
  "instance_count":2,"instance_size_slug":"apps-s-1vcpu-0.5gb", \
  "routes":[{"path":"/api"}]}]}}'
```

### Python

Using [PyDo](https://github.com/digitalocean/pydo), the official DigitalOcean API client for Python:

```python
import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

create_resp = client.apps.create(
    {
        "spec": {
            "name": "web-app",
            "region": "nyc",
            "services": [
                {
                    "name": "api",
                    "github": {},
                    "run_command": "bin/api",
                    "environment_slug": "node-js",
                    "instance_count": 2,
                    "instance_size_slug": "apps-s-1vcpu-0.5gb",
                    "routes": [],
                }
            ],
        }
    }
)
```

## Create an App Using the Control Panel

To create an app using the [DigitalOcean Control Panel](https://cloud.digitalocean.com), click **Create**, then select **App Platform** from the dropdown menu.

On the **Create an app** screen:

- Select your deployment source, either a Git repository or a [container image](https://docs.digitalocean.com/products/app-platform/how-to/deploy-from-container-images/index.html.md). If you have not previously created an app on App Platform, the repository service may prompt you to provide DigitalOcean with read permissions to your account.
- If using a Git repository, choose a branch to deploy from. By default, App Platform builds from the repository's root. If your code lives in a subdirectory (for example, in a [monorepo](https://docs.digitalocean.com/products/app-platform/how-to/deploy-from-monorepo/index.html.md)), set the source directory to match.
- Clear the **Autodeploy** checkbox if you want to stop automatic redeploys when the repository changes.
- Click **Next**.

![The Create an app screen with the Git repository tab selected, and GitHub selected as the Git provider.](https://docs.digitalocean.com/screenshots/app-platform/app-choose-source-repo.fd23836d71b5954a0b709640a8f6984cb718b6f0a3ae624e5ce3482748badccf.png)

App Platform retrieves your code, analyzes your repository, and automatically selects the appropriate runtime (such as Node or Ruby). If you need to override this behavior, upload a [Dockerfile](https://docs.docker.com/engine/reference/builder/) to your branch and restart the creation process.

### Configure Resource Settings

The **Resource settings** table displays configuration settings, some of which the detection system auto-fills. Click **Edit** beside settings you want to change.

![The Resource settings table showing the configuration settings for a web service.](https://docs.digitalocean.com/screenshots/app-platform/app-config-options.12ca98dc05f39b05fb91849e9fe38d3c116fc66f9aa1a1c19c2b4819afc5bc3c.png)

You can configure the following settings:

- **Name:** A unique name for the component.
- **Resource type:** The type of component to deploy (web service, static site, worker, or job).

  **Note**: The selected **Resource type** determines which fields in the following list are displayed in the **Resource settings** table.
- **Branch:** The branch to deploy from. You can enable automatic redeploys when changes are made to this branch.
- **Instance size:** The amount of memory (RAM), CPUs, and bandwidth allocated to the component. You can choose shared or dedicated CPUs. Shared CPUs share their processing power with other DigitalOcean users. Dedicated CPUs are dedicated solely to your app. We recommend dedicated CPUs for more resource-intensive applications that require consistent high performance and autoscaling.
- **Containers:** The component's scaling settings. The instance size you select determines the scaling options available. For more details, see [How to Scale Apps in App Platform](https://docs.digitalocean.com/products/app-platform/how-to/scale-app/index.html.md).
- **Build command:** A custom build command to run before the app is deployed. This is useful for compiling assets, installing dependencies, or running tests before deployment.
- **Run command:** A custom run command for the application to run after deployment. If no run command is specified, the default run command for your app's language is used, such as `npm start` for a Node.js app. For Dockerfile-based builds, entering a run command overrides the Dockerfile's entrypoint.
- **Output Directory:** For static sites only. An optional path to where the build assets are located, relative to the build context. If not set, App Platform automatically scans for these directory names: `_static`, `dist`, `public`, `build`.
- **Public HTTP port:** For web services only. The port that the app receives HTTP requests on. The default port is `8080`.
- **Internal ports:** For web services only. The port that the app receives internal requests on.
- **HTTP request routes:** For web services and static sites only. The URL path where the app can be accessed, such as `your-app-v3cl4.ondigitalocean.app/api`. If not specified, the app is accessible from the provided hostname's root.

  **Note**:

    The service must bind to and expose the HTTP port on the network interface `0.0.0.0`, rather than on the localhost (`localhost`) or loopback interface (`127.0.0.1`).

    Full HTTP request path preservation for services is not available in the Control Panel. Instead, set the `preserve_path_prefix` annotation in the [App Spec](https://docs.digitalocean.com/products/app-platform/reference/app-spec/index.html.md) to `true`.
- **Environment variables:** Key-value pairs available to your app at runtime that let you keep configuration separate from application code. Use them to provide secrets, API keys, and other external settings, such as connection details for an external database.

App Platform uses cloud-native buildpacks to build components and applies the buildpack's default build and run commands. See the [cloud-native buildpack reference](https://docs.digitalocean.com/products/app-platform/reference/buildpacks/index.html.md) for details about supported buildpacks.

### Add a Database

In the **Add a Database** section, you can connect a database to your app:

- To provision a new dev database directly within your app, click **Create dev database**.
- To connect an existing DigitalOcean Managed Database, click **Attach DigitalOcean database**.
- If your database is hosted outside of DigitalOcean, add environment variables in the **Resource settings** table to provide the connection details.

See [How to Manage Databases in App Platform](https://docs.digitalocean.com/products/app-platform/how-to/manage-databases/index.html.md) for details on connecting databases.

After connecting a dev or managed database, App Platform automatically injects the necessary connection information into the relevant component’s environment variables.

### Set App-Level Environment Variables

App-level environment variables are available to all components in your app. Use them for shared configuration, secrets, API keys, or other values your app needs at build time or runtime.

To set app-level environment variables:

- Click **Edit** in the **App-level environment variables** section.
- Click **Add environment variable**, type a key and value, then select a scope.
- Select **Encrypt** to obscure the value in build, deployment, and application logs.

For dynamic, app-specific variables that your app can reference, see [Use Bindable Variables](https://docs.digitalocean.com/products/app-platform/how-to/use-environment-variables/index.html.md#use-bindable-variables).

### Choose Datacenter Region

In the **Datacenter region** section, click the **Choose a datacenter region** dropdown menu, then select the region to deploy your app into. To minimize latency, choose the region geographically closest to your users.

Region selection is not available for static sites. Static resources are served through DigitalOcean’s [global CDN](https://docs.digitalocean.com/platform/regional-availability/index.html.md#app-platform-availability).

### Finalize

In the **Finalize** section, you can update the app's name and project:

- In the **Choose a unique app name** field, type a name for the app.
- In the **Select a project** dropdown menu, select an existing project and environment or click **Create new project**.
- If you create a new project, enter a name, then select a purpose and environment for the new project.

When finished, review your configuration settings and pricing details in the **Summary** section, then click **Create App**.

App Platform creates the app using the selected settings and deploys it automatically. After deployment, you can view it using the URL at the top of the app's **Overview** page.