Services
Create a service
Create an application, a database, a compose stack or a catalogue application in a project.
Updated
https://cloud.cahaves.com/api/projects/{slug}/services
Authorization
cahaves.cloud.sessionstringcookierequired
The session cookie Cloud sets when a customer signs in to the console with GitHub or Google. It is HttpOnly, so scripts cannot read it, and there are no API keys or tokens yet.
Path parameters
slugstringrequired
The project's slug. It is fixed when the project is created.
Example: "shop"
Headers
X-Cloud-Organizationstring<uuid>
The id of the organization the request works in, one the signed-in customer owns. Left out or empty, the request works in their oldest organization. Any other value answers 404 with `reason: "organization"`. A customer with no organization yet gets 409 "Create an organization first." from every route that works in one.
Example: "2f6c8e0a-4b1d-4e7f-9a3c-5d7e9f1b3a5c"
Body
application/jsonrequired
Exactly one of these shapes is accepted.
envstring
One NAME=value per line, at most 64 KB. For applications and compose stacks.
kindstringrequired
Allowed values: "application""database""compose"
namestringrequired
Trimmed of surrounding spaces. The engine derives its own name from it.
portinteger
The port the application listens on inside its container.
Default: 3000
sourceobject
For an application, where it comes from; for a compose stack, the file. A database takes none.
subtypestring
Required for a database.
Allowed values: "postgres""mysql""mariadb""mongo""redis"
versionstring | null
A database version the catalogue lists. Absent takes the newest.
replicasinteger
Applications only.
Default: 1
build_typestring | null
GitHub only. Absent, Cloud reads the repository and fills in the build type and every command not sent.
Allowed values: "nixpacks""dockerfile""railpack""static"null
build_commandstring | null
One line. GitHub only.
database_namestring
PostgreSQL, MySQL and MariaDB. Absent is `app`.
database_userstring
PostgreSQL, MySQL, MariaDB and MongoDB. Absent is `app`. MySQL keeps `root` for itself, and MariaDB keeps `root` and `mariadb.sys`. Redis always uses `default`.
instance_sizestring
Absent is `nano`, or `small` for a compose stack, which is charged at the dedicated rate where `nano` is not offered.
Allowed values: "nano""small""medium""large""xlarge"
start_commandstring | null
One line, run in place of the image's or the build's own command.
install_commandstring | null
One line. GitHub only.
database_passwordstring
12 to 128 letters, digits, dots, hyphens, underscores or tildes. Absent generates 32 letters and digits.
health_check_pathstring | null
A path the engine probes after each deploy, such as `/health`. Absent means no check.
publish_directorystring | null
For a static site, the directory the build writes, relative to the build path, such as `dist`.
backup_interval_hoursinteger | null
How often Cloud backs the new service up on its own: daily is 24, weekly 168, every 30 days 720, and null takes no automatic backup. Absent is daily for a PostgreSQL, MySQL, MariaDB or MongoDB database and for a catalogue application with a volume. Any other service answers 422 for a value other than null. The schedule is made only when platform backup storage is configured; without it the service is created with none. A MongoDB schedule dumps only the default `test` database.
Allowed values: 24168720null
Responses
application/json
The created service.
serviceobjectrequired
Creating a service never deploys it. Call Deploy a service when it is ready.
Creating a paid service is paid work, refused with 409 and a reason while the organization is not in good standing or is stopped for billing (Errors). The free nano application and the free nano database never are.
The body takes one of two shapes. The ordinary one names kind and, for an application, a source:
| Kind | Required | field on a fault |
|---|---|---|
| Application from an image | source.type: "image", source.image | source.image |
| Application from GitHub | source.type: "github", source.github_installation_id, source.github_repo_full_name, source.github_branch | any of them |
| Database | subtype; version is optional | subtype or version |
| Compose stack | source.compose_file, up to 256 KB | source.compose_file |
| Any | name, 1 to 40 characters | name |
An image reference is at most 255 characters with no spaces. A GitHub source created without build_type is read from the repository, as Build settings describes. An application's port is 3000 unless you send another.
A compose stack is charged at the dedicated rate, where nano is not offered, so it defaults to small and nano answers 422 with "Nano is not offered on dedicated capacity. Choose small or larger."
The catalogue shape names app instead, and Cloud fills in the image, port, command and environment from the entry. name defaults to the entry's name in lower case with hyphens, such as hermes-agent. instance_size defaults to the entry's minimum_size, and a smaller one answers 422 with a sentence such as "Hermes Agent needs small or larger."
backup_interval_hours asks for automatic backups: 24, 168 or 720, or null for none. It applies to PostgreSQL, MySQL, MariaDB and MongoDB databases and to catalogue applications with a volume, and defaults to 24 for them; any other service answers 422 for a value other than null. The schedule is made only when platform backup storage is configured, and the service is created without one otherwise.