Developers/Quick start

Quick start: deploy from GitHub

This guide deploys an app from a public GitHub repository with plain HTTP calls. You need:

• an app server, bought in the console under Servers & Billing;
• an API token with Read, Write, Deploy and Read sensitive data;
• curl and jq.

The examples use a Node app that listens on port 3000. Swap in your own repository and port.

1. Set up your shell#

export HOSTWOLF_APPS_TOKEN='12|your_token'
export API=https://console.app.hostwolf.net/api/v1
hw() { curl -sS --fail-with-body -H "Authorization: Bearer $HOSTWOLF_APPS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" "$@"; }

hw $API/team | jq '{id, name}'

hw is a small helper so the commands below stay short; --fail-with-body stops on errors and prints the API's message. If this prints your team, the token works.

2. Pick a server#

hw $API/hostwolf/servers | jq '.[] | {name, city, size, status, server_uuid}'
export SERVER=$(hw $API/hostwolf/servers | jq -r '[.[] | select(.kind == "app" and .status == "ready")][0].server_uuid')

server_uuid is what app creation needs. VPS entries have none: apps run on app servers.

3. Create a project#

export PROJECT=$(hw -X POST $API/projects -d '{"name": "hello"}' | jq -r .uuid)

A new project comes with a production environment.

4. Create the app#

export APP=$(hw -X POST $API/applications/public -d "{
  \"project_uuid\": \"$PROJECT\",
  \"environment_name\": \"production\",
  \"server_uuid\": \"$SERVER\",
  \"git_repository\": \"https://github.com/you/your-app\",
  \"git_branch\": \"main\",
  \"build_pack\": \"nixpacks\",
  \"ports_exposes\": \"3000\"
}" | jq -r .uuid)

• build_pack: nixpacks or railpack detect the language and build it for you; dockerfile uses the Dockerfile in the repository; static serves files.
• Leave out domains to get a generated HTTPS address under your server's name. To use your own, pass "domains": "https://shop.example.com" and point a DNS record at the server's IP.
• For a private repository, use /applications/private-deploy-key or /applications/private-github-app instead; see the API reference.

5. Set environment variables#

hw -X PATCH $API/applications/$APP/envs/bulk -d '{"data": [
  {"key": "NODE_ENV", "value": "production"},
  {"key": "SESSION_SECRET", "value": "change-me", "is_shown_once": true}
]}' | jq 'map(.key)'

is_shown_once hides a value for good after you save it.

6. Deploy and wait#

DEPLOYMENT=$(hw -X POST $API/applications/$APP/start | jq -r .deployment_uuid)

while :; do
  STATUS=$(hw $API/deployments/$DEPLOYMENT | jq -r .status)
  echo "$STATUS"
  case $STATUS in finished|failed|cancelled*) break ;; esac
  sleep 5
done

A first build usually takes one to three minutes. If it fails, the build log says why:

hw $API/deployments/$DEPLOYMENT | jq -r '.logs | fromjson | map(select(.hidden | not) | .output) | .[-30:][]'

7. Open it and read the logs#

hw $API/applications/$APP | jq -r .fqdn
hw "$API/applications/$APP/logs?lines=50" | jq -r .logs

fqdn lists the app's addresses, comma-separated. Logs need the Read sensitive data permission.

8. Clean up#

hw -X DELETE $API/applications/$APP
hw -X DELETE $API/projects/$PROJECT

Deleting an app also deletes its volumes unless you pass ?delete_volumes=false. A project can only be deleted once it's empty, so wait a few seconds after deleting the app.

Next steps#

• Deploy on every git push: push deploys.
• Add a database: managed databases.
• Handle more traffic: multi-server and autoscaling.
• The same flow in TypeScript is in the SDK quick start.