Deploy from your machine · Naijacloud docs

CLI

Deploy from your machine

Two commands cover going from an empty account to something running. `naijacloud deploy` ships the directory you are in, and `naijacloud launch` walks you through creating a project, an environment and a service in one pass.

6 min read

Deploy a static site

naijacloud deploy

That is the whole command. The first time in a directory it asks a few questions, deploys, and writes the answers to naijacloud.json. Every run after that takes no arguments.

first deploy

No naijacloud.json here — a few questions, then this is the last time.

  Site name         [acme-marketing]:
  Build command     (from package.json; 'none' to skip) [npm run build]:
  Output directory  (detected) [dist]:
  Single-page app?  (detected: React Router) [Y/n]:

Running `npm run build`
Packaged 18 files, 2.1 MB → 640 KB compressed
Uploading 640 KB
Created site acme-marketing
  QUEUED
  BUILDING
  RUNNING
https://acme-marketing.naijacloud.com
Wrote naijacloud.json

The defaults are detected locally. The output directory comes from the conventional build folders, the build command from package.json, and the SPA setting from the framework in your dependencies. Nothing is guessed over the network.

One question does read from the API: where the site should live. Services belong to an environment, so a static site is offered the same choice. Take the default and NaijaCloud places it for you, or pick a project / environment to put it in the tree.

The pipeline is: run the build, archive the output, request an upload slot, PUT the bytes to storage, then release. The first deploy creates a site. Every later one replaces it in place, atomically, on the same URL, with the previous version still serving if the new build fails.

`naijacloud.json`

naijacloud.json

{
  "$schema": "https://raw.githubusercontent.com/naijacloud/nc-cli/v1.0.0/schema/naijacloud.schema.json",
  "version": 1,
  "name": "acme-marketing",
  "serviceId": "svc_01HX…",
  "environmentId": "env_01HX…",
  "build": "npm run build",
  "output": "dist",
  "spa": true,
  "ignore": ["**/*.map"]
}

Field	Purpose
`name`	Site name, used for the subdomain. First deploy only
`serviceId`	Written by the first successful deploy. Its presence is what makes the next deploy a redeploy
`environmentId`	The environment the site was created in. Absent when NaijaCloud placed the site itself
`build`	Run locally before archiving. A non-zero exit aborts before anything uploads
`output`	Directory to deploy, relative to the manifest. May be a single `.html` file
`spa`	Serve the entry file for unmatched paths, so client-side routes survive a refresh
`index`	Entry file, when it is not `index.html`
`ignore`	Globs excluded from the archive

Commit the file. The serviceId is not a secret and is only actionable with credentials for the owning team. Committing it is what lets CI deploy from a clean checkout with no linking step.

.git, node_modules, .naijacloud and every .env file are excluded from the archive whatever ignore says. A static bundle is world readable by definition, so there is no case for uploading one.

Options

Flag	Effect
`--prebuilt`	Skip the build command. The output is already built
`--new`	Create a new site, ignoring the manifest's `serviceId`
`--env <project/environment>`	Create the site in a specific environment
`--yes`	Accept detected defaults instead of prompting. Required for a first deploy in CI
`--no-wait`	Return as soon as the build is queued
`--json`	Machine readable result on stdout
`--name` `--output` `--index` `--spa`	One-off overrides of the manifest fields

A positional path deploys that directory directly, already built:

naijacloud deploy ./dist

Write the manifest without deploying

naijacloud init          # same questions, same file, no deploy
naijacloud init --yes    # accept every detected default
naijacloud init --force  # rewrite an existing manifest

Useful when configuring the repo and shipping the site are separate acts, such as setting up CI before the first build exists.

Start from nothing

The platform models everything as team, then project, then environment, then service. All four have to exist before anything runs. naijacloud launch creates each level that is missing, in one pass.

naijacloud launch

It walks you through picking or creating the project and environment, connecting a repo or choosing a static directory, and handing over your .env so the first build already has its configuration.

The same steps with flags, which is what launch calls underneath:

naijacloud projects create storefront --team acme
naijacloud environments create prod --project storefront
naijacloud services create api \
  --env storefront/prod \
  --repo acme/storefront --branch main \
  --build "npm run build" --start "npm start" --port 3000 \
  --dotenv .env

services create also takes --type cron --schedule "0 3 * * *", --root-dir for a monorepo, --runtime-version, --health-check, --region, --tier and --no-wait.

A web service comes from a repository. NaijaCloud builds a web service from a connected GitHub repo or runs a prebuilt image. There is no upload-and-build path for one. The only thing that accepts bytes from your machine is a static site.

If the team has no GitHub App installation yet, launch prints the install URL rather than failing.

Deploy from CI

.github/workflows/deploy.yml

- run: npm ci && npm run build
- run: npx @naijacloud/cli deploy --prebuilt --yes --json
  env:
    HOSTING_API_TOKEN: ${{ secrets.NAIJACLOUD_TOKEN }}

--prebuilt skips the manifest's build command, since CI has already run it. --yes is required for a first deploy, where there is no manifest to read defaults from. deploy waits for the build and exits non-zero if it fails, so it gates the job on its own.

Next steps

Command reference →

Projects, services, deploys, variables, domains and the database console.

Static sites →

How static hosting works on the platform.

← Previous

Install the CLI

Command reference