Deployments

Deploy project

Upload a ZIP and start one end-to-end deployment operation.

POST/api/v1/deploy

Send archive and metadata multipart parts. The proxied archive maximum is 95,000,000 bytes.

Authentication: REST bearer token required.

Build and ZIP your project

Choose the project type or Node package manager that matches the files you will send. Each recipe verifies the project locally and creates the site.zip archive used by the multipart REST request.

Static HTML

Package static files from their final root

Use this for hand-authored HTML/CSS/JavaScript or an already-built static output directory. Run the commands inside the directory that directly contains index.html.

Keep index.html at the ZIP root.
Include referenced CSS, JavaScript, fonts, and images.
Upload site.zip as the REST archive part.

Terminal · static output

set -euo pipefail

test -f index.html
zip -qr site.zip . \
  -x ".git/*" ".env" ".env.*" "site.zip"
unzip -l site.zip | head

npm

Verify and package a Node project with npm

Use package-lock.json when it exists. The local build verifies the project; the ZIP keeps package.json and the lockfile so Sitedropper can detect and rebuild the application.

Run from the directory containing package.json.
Keep package-lock.json in the archive.
Exclude node_modules and every local environment file.

Terminal · npm

set -euo pipefail

if [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then
  npm ci
else
  npm install
fi
npm run build --if-present
zip -qr site.zip . \
  -x "node_modules/*" ".git/*" ".env" ".env.*" "site.zip"

pnpm

Verify and package a Node project with pnpm

Keep pnpm-lock.yaml and the packageManager declaration when present. Sitedropper uses those files to select pnpm during runtime detection.

Run from the directory containing package.json.
Keep pnpm-lock.yaml and workspace files in the archive.
Exclude node_modules and every local environment file.

Terminal · pnpm

set -euo pipefail

corepack enable
pnpm install --frozen-lockfile
if node -e "process.exit(require('./package.json').scripts?.build ? 0 : 1)"; then
  pnpm run build
fi
zip -qr site.zip . \
  -x "node_modules/*" ".git/*" ".env" ".env.*" "site.zip"

Yarn

Verify and package a Node project with Yarn

Keep yarn.lock and any checked-in Yarn configuration required by the project. Sitedropper uses the lockfile or packageManager declaration to select Yarn.

Run from the directory containing package.json.
Keep yarn.lock and required .yarn configuration in the archive.
Exclude node_modules and every local environment file.

Terminal · Yarn

set -euo pipefail

corepack enable
yarn install --frozen-lockfile
if node -e "process.exit(require('./package.json').scripts?.build ? 0 : 1)"; then
  yarn run build
fi
zip -qr site.zip . \
  -x "node_modules/*" ".git/*" ".env" ".env.*" "site.zip"

Python

Check and package a Python project

Install from the project’s declared dependency file, compile the source as a syntax check, and package source rather than the local virtual environment.

Keep requirements.txt, pyproject.toml, or Pipfile in the archive.
Keep the framework entry point such as main.py, app.py, or manage.py.
Exclude virtual environments, caches, and secrets.

Terminal · Python

set -euo pipefail

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
if [ -f requirements.txt ]; then
  python -m pip install -r requirements.txt
elif [ -f pyproject.toml ]; then
  python -m pip install .
elif [ -f Pipfile ]; then
  python -m pip install pipenv
  pipenv install --dev
fi
python -m compileall -q .
zip -qr site.zip . \
  -x ".venv/*" "*/__pycache__/*" "*.py[cod]" ".git/*" ".env" ".env.*" "site.zip"

Dockerfile

Verify and package an existing Dockerfile project

Build the image locally from the same context you will archive. Sitedropper detects the existing Dockerfile and uses it instead of generating one.

Run from the Docker build context.
Keep Dockerfile and .dockerignore in the archive.
Do not include credentials through COPY or local environment files.

Terminal · Dockerfile

set -euo pipefail

docker build --tag sitedropper-preview .
zip -qr site.zip . \
  -x ".git/*" ".env" ".env.*" "site.zip"

Archive rule: keep secrets and local dependency directories out of site.zip. For an already-built static site, select Static HTML and run the command inside the final output directory.

Parameters

Idempotency-Keystringoptional

HeaderA caller-generated key, up to 200 characters, that safely identifies a retried deployment.

archiveZIP filerequired

BodyThe project ZIP in the archive multipart part.

metadataJSONrequired

BodyA JSON multipart part containing deployment metadata.

metadata.project_idUUIDoptional

MetadataDeploy into an existing project. Omit to create a project.

metadata.namestringoptional

MetadataName for a newly created project. Required when project_id is omitted.

metadata.descriptionstringoptional

MetadataProject description used when creating a project.

metadata.visibilitystringoptional

Metadatadraft, private, password, or public. Defaults to draft for new projects.

metadata.access_passwordstringoptional

MetadataRequired when visibility is password.

metadata.filenamestringoptional

MetadataOverride the uploaded archive filename.

metadata.variablesobjectoptional

MetadataEnvironment variable name/value pairs to store for the deployment.

metadata.configurationobjectoptional

MetadataOptional runtime, framework, command, port, root-directory, Dockerfile, and skip-build overrides.

Responses

202

The aggregate deployment operation was accepted. Location points to operation polling.

400

The request is invalid or contains an unsupported value.

401

The bearer token is missing, invalid, or expired.

403

The account plan or current grant does not allow the action.

413

The ZIP exceeds the active upload transport limit.