Projects, services and deploys

The provisioning path in four requests. Create a project, pick its environment, create a service, then deploy it and watch it go live.

6 min read

The shape

A workspace holds projects. A project holds environments, and an environment holds services. A service is the unit that runs: a web app, a static site, a cron job or a managed database. See core concepts for how they relate.

The first three steps need WRITE and PLATFORM_API. Deploying needs WRITE and DEPLOYS. Get the workspace id once from GET /v1/workspaces and keep it.

1. Create a project

bash

curl -X POST "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/projects" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-storefront" \
  -d '{"name":"storefront","region":"af-west"}'

name is slug-shaped and unique in the workspace. displayName, description and region are optional. region sets where the project's services go unless a service names another one.

2. Pick an environment

A new project already has a dev environment. Read it rather than creating one: a second dev is refused.

The project's environments

bash

curl "https://api.naijacloud.com/v1/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer $NC_API_KEY"

To add another one, such as prod, post its name:

Add an environment

bash

curl -X POST "https://api.naijacloud.com/v1/projects/$PROJECT_ID/environments" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod"}'

3. Create a service

One route creates every kind of service. name and type are always required. The rest depends on the type and on where the code comes from.

Code comes from	Set
A public Git repository	`gitUrl`, `branch`
A repository through the GitHub App	`repoFullName`, `branch`, `installationId`
A container image	`image`, optionally `imageCommand`

sourceType is inferred from whichever of those you send. The fields you will use most:

Field	Notes
`type`	`WEB`, `STATIC`, `CRON`, `POSTGRES`, `MYSQL`, `MARIADB`, `MONGODB`, `REDIS`, `VALKEY`
`tier`	`FREE`, `STARTER`, `STANDARD`, `PRO`. Sizes and prices are on the pricing page
`region`	`af-west` or `eu-west`. Defaults to the project's region
`port`	The port your app listens on. Set it: a wrong one is a 502 nothing else explains
`buildCommand`, `startCommand`	Override what the builder detected
`rootDir`	For an app inside a monorepo
`envVars`	`[{ "key": "…", "value": "…" }]`, set before the first build
`schedule`, `command`	`CRON` only. Five-field cron, in UTC

bash

curl -X POST "https://api.naijacloud.com/v1/environments/$ENVIRONMENT_ID/services" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-storefront-api" \
  -d '{
    "name": "storefront-api",
    "type": "WEB",
    "gitUrl": "https://github.com/acme/storefront",
    "branch": "main",
    "tier": "STARTER",
    "port": 3000,
    "envVars": [{ "key": "NODE_ENV", "value": "production" }]
  }'

A managed database is the same request with a data type and no source:

A Postgres database

json

{ "name": "storefront-db", "type": "POSTGRES", "tier": "STARTER" }

Creating a service queues its first deploy. Its status goes from PROVISIONING to ACTIVE, and url fills in once it is reachable. A paid tier needs balance in the workspace: without it the request is 402 PAYMENT_REQUIRED.

4. Deploy and watch it

Deploy again after a change, or to restart a service, with POST /v1/services/{serviceId}/deploys. It needs DEPLOYS.

bash

curl -X POST "https://api.naijacloud.com/v1/services/$SERVICE_ID/deploys" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: storefront-api-release-42"

A deploy moves through QUEUED, BUILDING and DEPLOYING to RUNNING, or stops at FAILED. SUPERSEDED means a newer deploy overtook this one, which is normal when you push twice. It is not a failure. When a deploy fails, error says why in plain words and errorCode is stable to branch on.

The build log is a paginated list of lines, oldest first:

Build log

bash

curl "https://api.naijacloud.com/v1/deploys/$DEPLOY_ID/logs?limit=100" \
  -H "Authorization: Bearer $NC_API_KEY"

Rolling back reuses a previous deploy's image, so nothing rebuilds:

Roll back

bash

curl -X POST "https://api.naijacloud.com/v1/deploys/$GOOD_DEPLOY_ID/rollback" \
  -H "Authorization: Bearer $NC_API_KEY"