# Create a Ubuntu service in Zerops Zerops provides a Ubuntu runtime service with extensive build support. Ubuntu runtime is highly scalable and customisable to suit both development and production. ## Create Ubuntu service using Zerops GUI First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Ubuntu service: ### Choose Ubuntu version Following Ubuntu versions are currently supported: :::info You can [change](/ubuntu/how-to/upgrade) the major version at any time later. ::: ### Set a hostname Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden. #### Limitations: - maximum 25 characters - must contain only lowercase ASCII letters (a-z) or numbers (0-9) :::caution The hostname is fixed after the service is created. It can't be changed later. ::: ### Set secret environment variables Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start. Setting the secret environment variables is optional. You can set them later in Zerops GUI. Read more about [different types of env variables](/ubuntu/how-to/env-variables#service-env-variables) in Zerops. ### Configure auto scaling Zerops automatically scales Ubuntu services both vertically and horizontally. Configure the scaling parameters to match your application's needs and control costs. #### Quick Configuration **CPU Mode**: Choose between shared (cost-effective) or dedicated (consistent performance). **Resource Limits**: Set minimum and maximum resources for CPU, RAM, and disk to control costs and ensure performance. **Advanced Resource Settings**: Beyond the basic limits, Zerops provides additional scaling parameters for fine-tuning performance: - **Start CPU cores** - Allocate extra CPU power during application startup - **RAM thresholds** - Prevent out-of-memory crashes with custom buffer settings - **CPU scaling thresholds** (dedicated mode) - Control when scaling is triggered These settings can significantly improve application performance and reliability. See the scaling guides below for detailed configuration options. **Container Limits**: Configure horizontal scaling from 1 to 10 containers. - **Single container** (max = 1): Cost-effective for development, but no high availability - **Multiple containers** (max > 1): High availability for production, requires stateless application design :::tip Learn More For detailed scaling configuration, troubleshooting, and best practices, see: - [How Zerops scales Ubuntu](/ubuntu/how-to/scaling) - Service-specific scaling guide - [Automatic Scaling and High Availability](/features/scaling) - Complete technical details - [Zerops Pricing](https://zerops.io/#pricing) - Cost differences between CPU modes and resource usage rates ::: ## Create Ubuntu service using zCLI zCLI is the Zerops command-line tool. To create a new Ubuntu service via the command-line, follow these steps: 1. [Install & setup zCLI](/references/cli) 2. [Create a project description file](/ubuntu/how-to/create#create-a-project-description-file) 3. [Create a project with a Ubuntu and PostgreSQL service](#full-example) ### Create a project description file Zerops uses a yaml format to describe the project infrastructure. #### Basic example: Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content: ```yaml # basic project data project: # project name name: my-project # array of project services services: - # service name hostname: app # service type and version number in ubuntu@{version} format type: ubuntu@24.04 # defines the minimum number of containers for horizontal autoscaling minContainers: 1 # defines the maximum number of containers for horizontal autoscaling. Max value = 6. maxContainers: 6 # optional: create env variables envSecrets: S3_ACCESS_KEY_ID: 'P8cX1vVVb' S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ' ``` The yaml file describes your future project infrastructure. The project will contain one Ubuntu service with default [auto scaling](/ubuntu/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/ubuntu/how-to/build-pipeline#ports). Following secret env variables will be configured: ```env S3_ACCESS_KEY_ID="P8cX1vVVb" S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ" ``` #### Full example: Create a directory my-project. Create an description.yaml file inside the my-project directory with following content: ```yaml # basic project data project: # project name name: my-project # optional: project description description: A project with a Ubuntu and PostgreSQL database # optional: project tags tags: - DEMO - ZEROPS # array of project services services: - # service name hostname: app # service type and version number in ubuntu@{version} format type: ubuntu@24.04 # optional: vertical auto scaling customization verticalAutoscaling: cpuMode: DEDICATED minCpu: 2 maxCpu: 5 minRam: 2 maxRam: 24 minDisk: 6 maxDisk: 50 startCpuCoreCount: 3 minFreeRamGB: 0.5 minFreeRamPercent: 20 # defines the minimum number of containers for horizontal autoscaling. Max value = 6. minContainers: 2 # defines the maximum number of containers for horizontal autoscaling. Max value = 6. maxContainers: 4 # optional: create secret env variables envSecrets: S3_ACCESS_KEY_ID: 'P8cX1vVVb' S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ' - # second service hostname hostname: db # service type and version number in postgresql@{version} format type: postgresql@12 # mode of operation "HA"/"non_HA" mode: NON_HA ``` The yaml file describes your future project infrastructure. The project will contain a Ubuntu service and a [PostgreSQL](/postgresql/overview) service. Ubuntu service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Ubuntu service will run with a custom vertical and horizontal scaling. Following secret env variables will be configured: ```env S3_ACCESS_KEY_ID="P8cX1vVVb" S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ" ``` The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set. #### Description of description.yaml parameters The `project:` section is required. Only one project can be defined.
Parameter Description
hostname The unique service identifier. The hostname of the new database will be set to the `hostname` value. Limitations:
  • duplicate services with the same name in the same project are forbidden
  • maximum 25 characters
  • must contain only lowercase ASCII letters (a-z) or numbers (0-9)
type Specifies the service type and version. See what [Ubuntu service types](/references/import-yaml/type-list#runtime-services) are currently supported.
verticalAutoscaling Optional. Defines [custom vertical auto scaling parameters](/ubuntu/how-to/create#set-auto-scaling-configuration). All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
- cpuMode Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
- minCpu/maxCpu Optional. Set the minCpu or maxCpu in CPU cores (integer).
- minRam/maxRam Optional. Set the minRam or maxRam in GB (float).
- minDisk/maxDisk Optional. Set the minDisk or maxDisk in GB (float).
minContainers Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/ubuntu/how-to/create#horizontal-auto-scaling). Limitations: Current maximum value = 10.
maxContainers Defines the maximum number of containers for [horizontal autoscaling](/ubuntu/how-to/create#horizontal-auto-scaling). Limitations: Current maximum value = 10.
envSecrets Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/ubuntu/how-to/env-variables#env-variable-restrictions).
### Create a project based on the description.yaml When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure. ```sh Usage: zcli project project-import importYamlPath [flags] Flags: -h, --help Help for the project import command. --org-id string If you have access to more than one organization, you must specify the org ID for which the project is to be created. --working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./") ``` Zerops will create a project and one or more services based on the `description.yaml` content. Maximum size of the `description.yaml` file is 100 kB. You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`. If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page. ### Add Ubuntu service to an existing project #### Example: Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content: ```yaml # basic project data project: # project name name: my-project # array of project services services: - # service name hostname: app # service type and version number in ubuntu@{version} format type: ubuntu@24.04 # defines the minimum number of containers for horizontal autoscaling minContainers: 1 # defines the maximum number of containers for horizontal autoscaling. Max value = 6. maxContainers: 6 # optional: create env variables envSecrets: S3_ACCESS_KEY_ID: 'P8cX1vVVb' S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ' ``` The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Ubuntu service version 1 with default [auto scaling](/ubuntu/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured: ```env S3_ACCESS_KEY_ID="P8cX1vVVb" S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ" ``` The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists. When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project. ```sh Usage: zcli project service-import importYamlPath [flags] Flags: -h, --help Help for the project service import command. -P, --project-id string If you have access to more than one project, you must specify the project ID for which the command is to be executed. ``` zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from. Maximum size of the import.yaml file is 100 kB.