Skip to main content

​
Required files

Upsun uses a YAML configuration file to control your application’s behavior. Place this file inside a .upsun/ folder at the root of your source code:
Example file structure
my-app
├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>
To generate these YAML files, run the following command from the root of your project:
Terminal
upsun project:init
Follow the prompts. The upsun project:init command does the following:
  • Detects your framework automatically. If it can’t, it asks which runtime language your codebase uses.
  • Asks if you want to add any services.
  • Generates the .upsun/config.yaml and .environment files.
The generated configuration varies slightly based on your answers and whether a framework is detected. The file structure looks similar to the following: 
applications:
  # Configuration for all applications within an environment.
  myapp:
    # configuration for the application 'myapp'

services:
  # Configuration for all services within an environment.
  db:
    # configuration for service 'db'

routes:
  # Configuration for routing to applications
  'https://{default}/':
The top-level keys map to:
  • applications: configuration for all applications within an environment
  • services: configuration for all services within an environment
  • routes: configuration for how requests are handled by the router
For more information on the structure of this configuration file, see the YAML structure page.

Committing variables

An additional .environment file may be located at the root of your source code. This file contains Upsun-specific environment variables.
Commit your new files:
Terminal
git add . && git commit -m "Add configuration for Upsun."
Push to your Upsun project: 
upsun push
Upsun reads your configuration files, builds your application image, and allocates resources to your containers.
By default, Upsun uses default resources for each of your services and apps. You can adjust these resources.

​
Errors on first push

If you push code without an Upsun configuration, the following error appears: 
Found 749 commits

E: Error parsing configuration files:
- : Configuration directory '.upsun' not found.

E: Error: Invalid configuration files, aborting build
Add the configuration files described above and push again.

​
Configuration errors

The project:init command uses your responses and framework-detection logic to generate a starting configuration. Because every project is different, the generated configuration may not cover all your requirements. Upsun provides a customizable configuration schema you can adjust for your package manager, environment variables, builds, deploys, workers, crons, and other requirements. To explore what might still be needed, see the language-specific configuration pages:

​
Next steps

After deployment, Upsun sets resources for your application and service containers automatically:
Each time you create a new branch, your new environment inherits its parent environment’s resource allocation.
If you need more disk for uploaded files, or less memory for rarely used services, you can adjust resources at any time.
Last modified on April 29, 2026