---
title: service.yml
url: "/docs/blossom-cli/service-yml/"
canonical_url: https://docs.blossom88.com/docs/blossom-cli/service-yml/
markdown_url: https://docs.blossom88.com/docs/blossom-cli/service-yml.md
summary: service.yml example for an application Service
categories:
- cli
- services
---

# service.yml

A Service is a long-running application workload in an Environment. Use one
Service for each independently scalable process such as `web`, `worker`, or
`scheduler`.

Create a starter file:

```sh
blossom service:init
```

It writes service.yml:

```yaml
service:
  environment_id: environment-100 # replace with your environment id
  name: web
  command: bundle exec puma
  port: 3000
  publicly_exposed: true
  desired_size: 1
  health_check:
    enabled: false
    kind: http
    path: /ready
    traffic: true
  resources:
    preset: small # micro, small, medium, large, x-large, 2x-large, 4x-large, 8x-large, or custom
```

Create the Service:

```sh
blossom service:create --data service.yml
```

The Environment supplies the deployed image and Environment variables.
Environment Links add private Database and Cache connection URLs to every
Service in the Environment.

The health check belongs to this Service because it verifies this process and
port. Blossom uses the same definition to hold a new Release until its
Containers are ready and, when `traffic` is enabled, to stop routing to an
unhealthy Container. Private workers can use `kind: command` with a command
that exits successfully when the process is healthy.

Every running container receives an explicit allocation. The default is
`small` (`0.5 vCPU / 875 MB`), which fits four Containers in one
`2 vCPU / 4 GB` Capacity unit. Choose `micro` (`0.25 vCPU / 437.5 MB`)
for lighter workloads; eight fit in that unit. `medium` (`1 vCPU / 1.75 GB`) fits
two per unit and `large` (`2 vCPU / 3.5 GB`) fills one whole unit. `x-large`
(`4 vCPU / 7.8 GB`) fills two Capacity units on one Server, and each size
above it doubles the last: `2x-large` (`8 vCPU / 15.6 GB`), `4x-large`
(`16 vCPU / 31.2 GB`), and `8x-large` (`32 vCPU / 62.4 GB`). Each size is what
its Server has left after Linux and Blossom's agent, so sizes pack units with
nothing stranded. For a custom allocation:

```yaml
  resources:
    preset: custom
    cpu_vcpus: 1.5
    memory_gb: 3
```

Custom allocations require at least `0.05 vCPU` and `67,108,864 bytes`. CPU
uses `0.05 vCPU` increments; memory uses decimal GB with whole-byte precision.
Blossom rejects
unsupported values instead of rounding them. A custom Container above 3.5 GB
selects a larger physical Server shape; Blossom never combines several smaller
Servers to pretend that one Container fits. These values determine Container
limits and the Blossom charge.

Use [Databases](/docs/databases/) or
[Caches](/docs/caches/) for supported data engines. They use their
own managed-data lifecycle rather than application Service scaling.

## Persistent Services

For a custom single-writer workload, add this under `service`:

```yaml
  storage:
    size_gib: 10
    mount_path: /data
    availability: shared
```

Keep `desired_size: 1`. Shared runs on your own Persistent Capacity; `dedicated`
reserves compute for this Service. Each keeps its own Volume. Deployments stop
the previous writer first, and replacement can interrupt availability. Storage
survival is not an application backup.

Increase `size_gib` to grow a ready Volume; shrinking or changing its path is
refused. Deletion requires [an explicit storage choice](/docs/reference/cli/service/delete/): `retain` preserves the disabled
Service and billed Volume, while `delete` permanently removes both.