User Documentation


Sign up for Upsun

Get your free trial by clicking the link below.

Get your Upsun free trial

Each environment you deploy on is built as a set of containers. Each container is an isolated instance with specific resources.

Each environment has 2 to 4 types of containers:

If you have two app containers, two services (a database and a search engine), and a worker, requests to your environment might look something like this:

A user request goes to the router, which sends it to either a Node.js app or a Python app. Each app communicates separately with the database and search services and sends responses to the user. The Node.js app triggers actions in a worker, which communicates separately with the database.

If you have only one app container, your repository might look like this:

โ”œโ”€โ”€ .git
โ”œโ”€โ”€ .platform
โ”‚   โ”œโ”€โ”€ routes.yaml
โ”‚   โ””โ”€โ”€ services.yaml
โ””โ”€โ”€ <YOUR_APP_FILES>

Router Anchor to this heading

Each environment always has exactly one router.

This router maps incoming requests to the appropriate app container and provides basic caching of responses, unless configured otherwise.

The router is configured in a .platform/routes.yaml file. If you don’t include configuration, a single default route is deployed.

Read more about how to define routes.

Apps Anchor to this heading

You always need at least one app container, but you can have more.

App containers run the code you provide via your Git repository. They handle requests from the outside world and can communicate with other containers within the environment. Each app container is built from a specific language image with a given version for the language.

To configure your apps, you usually create one file for each app container. A basic app generally has only one such file placed in the repository root.

Read more about how to configure apps.

Services Anchor to this heading

You don’t need any service containers, but you can add them as you like.

Service containers run predefined code for specific purposes, such as a database or search service. You don’t need to add their code yourself, just set up how your apps communicate with them.

Service containers are configured by the .platform/services.yaml file.

Read more about how to add services.

Workers Anchor to this heading

You don’t need any worker containers, but you can add them as you like.

Worker containers are copies of an app containers that have no access to the outside world and can have a different start command. They’re useful for continually running background processes.

Read more about how to work with workers.

Is this page helpful?