Skip to main content

Quick Start

Deploy your first project in 5 minutes.

Prerequisites​

  • A GitHub or GitLab account
  • A repository with a Dockerfile (or a supported runtime — Node.js, Python, Java)
  • A Swisblade account

Step 1: Create stack.json​

Add a stack.json file to the root of your repository:

{
  "name": "hello-world",
  "services": {
    "api": {
      "source": { "repo": "github.com/you/hello-world.git", "ref": "main" },
      "type": "app",
      "runtime": "node",
      "port": 3000,
      "public": true
    }
  }
}

This defines a single service that will be built from your repo and exposed publicly.

No Dockerfile?

If your repo doesn't have a Dockerfile, Swisblade auto-detects your runtime and builds one for you using Nixpacks. Supported runtimes: Node.js, Python, Java.

Step 2: Create a project​

  1. Go to the dashboard and click Create Project.
  2. Choose how to define your stack:
    • Git Repo — Point to a repository that contains a stack.json.
    • Visual Builder NEW — Build your stack visually with forms — no JSON needed. Pick services, databases, runtimes, and connections from a UI.
    • stack.json — Paste your stack.json directly.
  3. Enter a project name (e.g., hello-world).
  4. If using Git Repo or Visual Builder with private repos, provide a Personal Access Token (PAT).
  5. Click Create & Deploy.
Don't know JSON?

Use the Visual Builder tab to assemble your stack with a form. Add app services, containers, and databases, select infrastructure (PostgreSQL, Redis, etc.), and connect services together — all without writing a single line of JSON. The builder generates the exact same stack.json behind the scenes.

Step 3: Watch the deploy​

The dashboard shows a real-time deploy log. You'll see:

  1. Cloning your repository
  2. Building the Docker image
  3. Starting the container
  4. Health check passing

Once the deploy succeeds, your service is live.

Step 4: Access your app​

Your public service is available at:

https://api-{project-slug}.swisblade.com

The project slug is shown in the dashboard (e.g., a1b2c3d4-hello-world).

Step 5: Add a database​

Need a database? Update your stack.json:

{
  "name": "hello-world",
  "services": {
    "api": {
      "source": { "repo": "github.com/you/hello-world.git", "ref": "main" },
      "type": "app",
      "runtime": "node",
      "port": 3000,
      "public": true,
      "needs": ["postgres"]
    }
  }
}

Commit, push, and redeploy from the dashboard. Swisblade will:

  1. Provision a PostgreSQL database
  2. Create a dedicated user with connection limits
  3. Inject DATABASE_URL into your service automatically

Your app can use process.env.DATABASE_URL immediately — no configuration needed.

What's next​