Quick Start

Your first deployment, step by step. Five minutes from now, you'll have a live web application with a public URL.

What We'll Build

A simple FastAPI web server that:

Responds to HTTP requests
Runs on Basilica infrastructure
Has a public URL you can share

Prerequisites

Before starting, ensure you have:

Python 3.9+ installed
Basilica CLI installed
Basilica SDK installed (pip install basilica-sdk)
Authenticated with Basilica (basilica login)

If you haven't completed these steps, see Installation first.

Step 1: Create Your Project

Create a new directory for your project:

mkdir hello-basilica
cd hello-basilica

Step 2: Write the Deployment Script

Create a file called deploy.py:

import basilica

@basilica.deployment(
    name="hello-world",
    port=8000,
    pip_packages=["fastapi", "uvicorn"],
)
def serve():
    from fastapi import FastAPI
    from datetime import datetime
    import uvicorn

    app = FastAPI(title="Hello Basilica")

    @app.get("/")
    def index():
        return {
            "message": "Hello from Basilica!",
            "timestamp": datetime.now().isoformat()
        }

    @app.get("/health")
    def health():
        return {"status": "healthy"}

    uvicorn.run(app, host="0.0.0.0", port=8000)

deployment = serve()
print(f"URL: {deployment.url}")

Step 3: Deploy

Run it:

python deploy.py

You'll see output like:

Deploying application...
✓ Deployed successfully!
  Name: hello-world
  URL:  https://5c3d6478-f62f-4349-8954-cb89e8db1e7c.basilica.ai
  State: running

Step 4: Test Your Deployment

Open the URL in your browser, or use curl:

curl https://5c3d6478-f62f-4349-8954-cb89e8db1e7c.basilica.ai

Response:

{
  "message": "Hello from Basilica!",
  "timestamp": "2024-01-15T10:30:00.123456"
}

Test the health endpoint:

curl https://5c3d6478-f62f-4349-8954-cb89e8db1e7c.basilica.ai/health

Response:

{
  "status": "healthy"
}

Step 5: Monitor Your Deployment

View Logs

Stream logs from your deployment:

basilica deploy logs 5c3d6478-f62f-4349-8954-cb89e8db1e7c

Or in Python:

for log in client.logs("5c3d6478-f62f-4349-8954-cb89e8db1e7c"):
    print(log)

Check Status

Check deployment status:

deployment = client.get("5c3d6478-f62f-4349-8954-cb89e8db1e7c")
print(f"State: {deployment.state}")
print(f"URL: {deployment.url}")
print(f"Created: {deployment.created_at}")

List All Deployments

for d in client.list():
    print(f"{d.name}: {d.state}")

Step 6: Update Your Deployment

To update the application, deploy again with the same name:

updated_code = """
from fastapi import FastAPI
from datetime import datetime

app = FastAPI(title="Hello Basilica v2")

@app.get("/")
def index():
    return {
        "message": "Hello from Basilica v2!",
        "version": "2.0.0",
        "timestamp": datetime.now().isoformat()
    }

@app.get("/health")
def health():
    return {"status": "healthy", "version": "2.0.0"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
"""

deployment = client.deploy(
    name="hello-world",  # Same name updates the deployment
    source=updated_code,
    port=8000,
    pip_packages=["fastapi", "uvicorn"],
)

print(f"Updated! URL: {deployment.url}")

Step 7: Clean Up

Done experimenting? Delete the deployment to stop billing:

client.delete("5c3d6478-f62f-4349-8954-cb89e8db1e7c")
print("Deployment deleted!")

Or via CLI:

basilica deploy down 5c3d6478-f62f-4349-8954-cb89e8db1e7c

Alternative: Deploy from File

Instead of using the decorator, you can deploy existing files with client.deploy():

app.py:

from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.get("/")
def hello():
    return {"message": "Hello from file!"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

deploy.py:

from basilica import BasilicaClient

client = BasilicaClient()

deployment = client.deploy(
    name="hello-from-file",
    source="app.py",
    port=8000,
    pip_packages=["fastapi", "uvicorn"],
)

print(f"URL: {deployment.url}")

Learn more in Deployments.

Troubleshooting

"Deployment failed" Error

Check the logs for details:

basilica deploy logs hello-world

Common causes:

Syntax errors in your code
Missing dependencies
Port conflicts

"Name already exists" Error

Each deployment name must be unique. Either:

Use a different name
Delete the existing deployment first

Application Not Responding

Verify your app listens on 0.0.0.0, not 127.0.0.1
Confirm the port matches what you specified
Check logs for startup errors

Slow Startup

First deployments may take longer as dependencies are installed. Subsequent deployments use cached dependencies.

Next Steps

You've deployed your first application. Go deeper:

Python SDK: Learn more SDK features
Storage: Add persistent storage
GPU Configuration: Run on GPU hardware
LLM Inference: Deploy language models

On this page