Skip to content
Klutch.sh Docs

Deploying an Actix App

Actix is a powerful, pragmatic, and extremely fast web framework for Rust. Built on the Actix actor framework, it combines high performance with type safety and excellent developer experience. Actix’s async/await support, middleware ecosystem, and composition model make it ideal for building production-grade web services, APIs, and microservices that require exceptional performance and reliability.

This guide explains how to deploy an Actix application to Klutch.sh, both with and without a Dockerfile, along with database configuration, environment setup, persistent storage, security patterns, and production deployment strategies.

Prerequisites

  • Rust 1.70 or higher
  • Cargo package manager
  • Git and a GitHub account
  • Klutch.sh account
  • Basic knowledge of Rust and async programming

Getting Started: Installing Rust and Creating an Actix App

  1. Install Rust (if not already installed):

    Use rustup for version management:

    Terminal window
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    source "$HOME/.cargo/env"
    rustup default stable

  2. Create a new Actix project:

    Terminal window
    cargo new my-actix-app
    cd my-actix-app

  3. Add dependencies to Cargo.toml:

    [package]
    name = "my-actix-app"
    version = "0.1.0"
    edition = "2021"
    

    [dependencies]
    actix-web = "4"
    actix-rt = "2"
    tokio = { version = "1", features = ["full"] }
    serde = { version = "1.0", features = ["derive"] }
    serde_json = "1.0"
    env_logger = "0.11"
    log = "0.4"
    dotenv = "0.15"
    sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres"] }
    uuid = { version = "1.0", features = ["v4", "serde"] }
    chrono = { version = "0.4", features = ["serde"] }

  4. Build the project:

    Terminal window
    cargo build

  5. Start the development server:

    Terminal window
    cargo run

    Your app should be running at http://localhost:8000.

Sample Code for Getting Started

Create a complete Actix application with routing and models:

use actix_web::{web, App, HttpServer, HttpResponse, Responder, middleware};
use serde::{Deserialize, Serialize};
use std::env;
use log::info;


#[derive(Serialize, Deserialize, Clone)]
pub struct Article {
    pub id: String,
    pub title: String,
    pub content: String,
    pub published: bool,
}


async fn index() -> impl Responder {
    HttpResponse::Ok().json(serde_json::json!({
        "message": "Welcome to Actix on Klutch.sh",
        "version": "1.0.0"
    }))
}


async fn health_check() -> impl Responder {
    HttpResponse::Ok().body("OK")
}


async fn create_article(article: web::Json<Article>) -> impl Responder {
    info!("Creating article: {}", article.title);
    HttpResponse::Created().json(article.into_inner())
}


async fn get_articles() -> impl Responder {
    let articles = vec![
        Article {
            id: "1".to_string(),
            title: "First Article".to_string(),
            content: "Content here".to_string(),
            published: true,
        }
    ];
    HttpResponse::Ok().json(articles)
}


#[actix_web::main]
async fn main() -> std::io::Result<()> {
    dotenv::dotenv().ok();
    env_logger::init_from_env(env_logger::Env::default().default_filter_or("info"));


    let port = env::var("PORT").unwrap_or_else(|_| "8000".to_string());
    let addr = format!("0.0.0.0:{}", port);


    info!("Starting Actix server on {}", addr);


    HttpServer::new(|| {
        App::new()
            .wrap(middleware::Logger::default())
            .route("/", web::get().to(index))
            .route("/health", web::get().to(health_check))
            .service(
                web::scope("/api/articles")
                    .route("", web::post().to(create_article))
                    .route("", web::get().to(get_articles))
            )
    })
    .bind(&addr)?
    .run()
    .await
}

Deploying Without a Dockerfile (Using Nixpacks)

Klutch.sh uses Nixpacks to automatically detect and build your Actix application. Nixpacks analyzes your project and determines the necessary dependencies, build steps, and runtime configuration.

Steps to Deploy with Nixpacks

  1. Prepare your Actix app for production:

    Update your .cargo/config.toml for optimized builds:

    [build]
    rustflags = ["-C", "target-cpu=native"]
    

    [profile.release]
    opt-level = 3
    lto = true
    codegen-units = 1
    strip = true

  2. Create a .cargo/config.toml if not present:

    This ensures Nixpacks correctly detects and builds your Rust project.

  3. Commit your code to GitHub:

    Terminal window
    git add .
    git commit -m "Initial Actix app setup"
    git push origin main

  4. Log in to Klutch.sh dashboard:

    Visit https://klutch.sh/app

  5. Create a new project:

    • Click “Create Project”
    • Enter your project name (e.g., “My Actix App”)
    • Select your organization or personal account

  6. Create a new app:

    • Click “Create App”
    • Select your Actix GitHub repository
    • Select the branch (typically main or master)
    • Select HTTP as the traffic type
    • Set the internal port to 8000 (the default Actix port)
    • Choose your desired region, compute power, and number of instances

  7. Add environment variables:

    In the app creation form, add these essential environment variables:

    RUST_LOG=info
    DATABASE_URL=postgresql://user:password@host:5432/myapp
    REDIS_URL=redis://user:password@host:6379/0
    PORT=8000

  8. Deploy:

    Click “Create” to deploy. Klutch.sh will automatically:

    • Detect your Rust/Actix project
    • Build with cargo build --release
    • Start the application on port 8000

Your app will be available at example-app.klutch.sh.

Customizing Build and Start Commands

If you need to customize the build or start command for Nixpacks, add these environment variables:

NIXPACKS_BUILD_CMD=cargo build --release
NIXPACKS_START_CMD=./target/release/my-actix-app

Deploying With a Dockerfile

For more control over your build process and runtime environment, you can provide a custom Dockerfile. Klutch.sh will automatically detect and use a Dockerfile in your repository’s root directory.

Creating a Multi-Stage Dockerfile

  1. Create a Dockerfile in your project root:

    # Build stage
    FROM rust:1.75-slim as builder
    

    WORKDIR /app
    

    # Install build dependencies
    RUN apt-get update && apt-get install -y build-essential pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*
    

    # Copy manifests
    COPY Cargo.toml Cargo.lock ./
    

    # Build dependencies - this is the caching layer
    RUN mkdir src && echo "fn main() {}" > src/main.rs && cargo build --release && rm -rf src
    

    # Copy source code
    COPY src ./src
    

    # Build application
    RUN cargo build --release
    

    # Runtime stage
    FROM debian:bookworm-slim
    

    RUN apt-get update && apt-get install -y ca-certificates libssl3 && rm -rf /var/lib/apt/lists/*
    

    WORKDIR /app
    

    # Copy binary from builder
    COPY --from=builder /app/target/release/my-actix-app .
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
      CMD curl -f http://localhost:8000/health || exit 1
    

    # Set environment
    ENV PORT=8000
    

    # Expose port
    EXPOSE 8000
    

    # Start application
    CMD ["./my-actix-app"]

  2. Commit the Dockerfile to GitHub:

    Terminal window
    git add Dockerfile
    git commit -m "Add production Dockerfile"
    git push origin main

  3. Log in to Klutch.sh dashboard:

    Visit https://klutch.sh/app

  4. Create a new app:

    • Click “Create App”
    • Select your Actix GitHub repository with the Dockerfile
    • Select the branch
    • Select HTTP as the traffic type
    • Set the internal port to 8000
    • Choose region, compute, and instances

  5. Add environment variables:

    RUST_LOG=info
    DATABASE_URL=postgresql://user:password@host:5432/myapp
    REDIS_URL=redis://user:password@host:6379/0
    PORT=8000

  6. Deploy:

    Click “Create”. Klutch.sh will automatically build your Docker image and deploy your app.

Database Configuration

Actix applications commonly use PostgreSQL or MySQL for data persistence. Here’s how to configure databases with Klutch.sh.

PostgreSQL Configuration

  1. Add SQLx to your Cargo.toml with PostgreSQL support:

    sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres", "macros"] }

  2. Create a database module (src/db.rs):

    use sqlx::postgres::PgPool;
    use std::env;
    

    pub async fn create_pool() -> Result<PgPool, sqlx::Error> {
        let database_url = env::var("DATABASE_URL")
            .expect("DATABASE_URL must be set");
    

        PgPool::connect(&database_url).await
    }
    

    pub async fn run_migrations(pool: &PgPool) -> Result<(), sqlx::Error> {
        sqlx::query(
            "CREATE TABLE IF NOT EXISTS articles (
                id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
                title VARCHAR NOT NULL,
                content TEXT NOT NULL,
                published BOOLEAN DEFAULT false,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
            )"
        )
        .execute(pool)
        .await?;
        Ok(())
    }

  3. Use the pool in your main application:

    mod db;
    

    #[actix_web::main]
    async fn main() -> std::io::Result<()> {
        let pool = db::create_pool().await.expect("Failed to create pool");
        db::run_migrations(&pool).await.expect("Failed to run migrations");
    

        HttpServer::new(move || {
            App::new()
                .app_data(web::Data::new(pool.clone()))
                // ... rest of your app
        })
        .bind("0.0.0.0:8000")?
        .run()
        .await
    }

  4. During app creation on Klutch.sh, set:

    DATABASE_URL=postgresql://username:password@postgres-host:5432/myapp_production

MySQL Configuration

  1. Add SQLx with MySQL support:

    sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "mysql"] }

  2. Update your database connection code:

    use sqlx::mysql::MySqlPool;
    

    pub async fn create_pool() -> Result<MySqlPool, sqlx::Error> {
        let database_url = env::var("DATABASE_URL")
            .expect("DATABASE_URL must be set");
    

        MySqlPool::connect(&database_url).await
    }

  3. Set the DATABASE_URL environment variable:

    DATABASE_URL=mysql://username:password@mysql-host:3306/myapp_production

Environment Variables

Actix applications use environment variables for configuration. Here are the essential variables:

RUST_LOG=info
PORT=8000
DATABASE_URL=postgresql://user:password@host:5432/dbname
REDIS_URL=redis://:password@redis-host:6379/0
API_KEY=<your-api-key>
JWT_SECRET=<your-jwt-secret>
ENVIRONMENT=production

Loading Environment Variables

Use the dotenv crate to load .env files locally:

use dotenv;


#[actix_web::main]
async fn main() -> std::io::Result<()> {
    dotenv::dotenv().ok();
    env_logger::init();
    // ... rest of your app
}

Async/Await and Concurrency

Actix is built on Tokio, providing excellent async support. Here’s how to leverage concurrency patterns:

Async Route Handlers

async fn get_article(id: web::Path<String>) -> impl Responder {
    let article_id = id.into_inner();
    // Async database query
    match fetch_article_from_db(&article_id).await {
        Ok(article) => HttpResponse::Ok().json(article),
        Err(_) => HttpResponse::NotFound().finish()
    }
}


async fn fetch_article_from_db(id: &str) -> Result<Article, sqlx::Error> {
    let pool = /* get your pool */;
    sqlx::query_as::<_, Article>("SELECT * FROM articles WHERE id = $1")
        .bind(id)
        .fetch_one(&pool)
        .await
}

Spawning Background Tasks

use actix_web::rt::task;


async fn create_article_with_processing(
    article: web::Json<Article>
) -> impl Responder {
    let article_data = article.into_inner();


    // Spawn background task
    task::spawn(async move {
        process_article(&article_data).await;
    });


    HttpResponse::Accepted().json(serde_json::json!({
        "status": "Processing"
    }))
}


async fn process_article(article: &Article) {
    // Long-running operation
    println!("Processing: {}", article.title);
}

Caching with Redis

Actix applications can leverage Redis for caching to improve performance:

  1. Add Redis crate to Cargo.toml:

    redis = { version = "0.25", features = ["aio"] }

  2. Create a cache utility module (src/cache.rs):

    use redis::aio::Connection;
    use std::env;
    

    pub async fn get_redis_connection() -> Result<Connection, redis::RedisError> {
        let redis_url = env::var("REDIS_URL").unwrap_or_else(|_| "redis://127.0.0.1".to_string());
        let client = redis::Client::open(redis_url)?;
        client.get_async_connection().await
    }
    

    pub async fn cache_get(conn: &mut Connection, key: &str) -> Result<Option<String>, redis::RedisError> {
        redis::cmd("GET").arg(key).query_async(conn).await
    }
    

    pub async fn cache_set_ex(
        conn: &mut Connection,
        key: &str,
        value: &str,
        ttl: usize,
    ) -> Result<(), redis::RedisError> {
        redis::cmd("SETEX").arg(key).arg(ttl).arg(value).query_async(conn).await
    }

  3. Use caching in handlers:

    async fn get_cached_article(id: web::Path<String>, redis: web::Data<Connection>) -> impl Responder {
        let article_id = id.into_inner();
        let cache_key = format!("article:{}", article_id);
    

        // Try cache first
        if let Ok(Some(cached)) = redis.get(&cache_key).await {
            return HttpResponse::Ok().body(cached);
        }
    

        // Fetch from database and cache
        if let Ok(article) = fetch_article(&article_id).await {
            let serialized = serde_json::to_string(&article).unwrap();
            let _ = redis.set_ex(&cache_key, &serialized, 3600).await; // 1 hour TTL
            return HttpResponse::Ok().json(article);
        }
    

        HttpResponse::NotFound().finish()
    }

  4. Set the REDIS_URL environment variable on Klutch.sh:

    REDIS_URL=redis://:password@redis-host:6379/0

Persistent Storage

Actix applications may need persistent storage for uploaded files or logs. Klutch.sh supports mounting persistent volumes.

Configuring File Storage

  1. Create a file handling module (src/storage.rs):

    use std::path::Path;
    use tokio::fs;
    

    pub async fn save_file(file_path: &str, content: &[u8]) -> Result<(), std::io::Error> {
        fs::write(file_path, content).await
    }
    

    pub async fn read_file(file_path: &str) -> Result<Vec<u8>, std::io::Error> {
        fs::read(file_path).await
    }
    

    pub async fn delete_file(file_path: &str) -> Result<(), std::io::Error> {
        fs::remove_file(file_path).await
    }

  2. Use persistent storage in handlers:

    #[post("/upload")]
    async fn upload_file(mut payload: web::Payload) -> impl Responder {
        let storage_path = std::env::var("STORAGE_PATH").unwrap_or_else(|_| "/tmp".to_string());
        let file_path = format!("{}/uploaded_file_{}", storage_path, uuid::Uuid::new_v4());
    

        // Save file from payload
        match save_file(&file_path, &payload.buffer().await.unwrap().to_vec()).await {
            Ok(_) => HttpResponse::Created().json(serde_json::json!({ "path": file_path })),
            Err(_) => HttpResponse::InternalServerError().finish()
        }
    }

  3. On Klutch.sh, attach a persistent volume:

    • During app creation, navigate to the “Storage” section
    • Click “Add Volume”
    • Set mount path to /app/storage
    • Allocate size (e.g., 10GB)

  4. Set the STORAGE_PATH environment variable:

    STORAGE_PATH=/app/storage

Security Best Practices

1. Use HTTPS Enforcement

Configure security headers in your Actix app:

use actix_web::middleware::DefaultHeaders;


HttpServer::new(|| {
    App::new()
        .wrap(DefaultHeaders::new().add(("Strict-Transport-Security", "max-age=31536000; includeSubDomains")))
        .wrap(DefaultHeaders::new().add(("X-Content-Type-Options", "nosniff")))
        .wrap(DefaultHeaders::new().add(("X-Frame-Options", "DENY")))
        // ... rest of your app
})

2. Implement CORS for APIs

Add CORS support:

use actix_cors::Cors;


App::new()
    .wrap(
        Cors::default()
            .allow_any_origin()
            .allow_any_method()
            .allow_any_header()
            .max_age(3600)
    )

3. Add Request Validation

Use Serde for automatic validation:

use serde::{Deserialize, Serialize};


#[derive(Deserialize, Serialize)]
pub struct CreateArticleRequest {
    #[serde(alias = "title")]
    pub title: String,
    #[serde(alias = "content")]
    pub content: String,
}


#[post("/articles")]
async fn create_article(req: web::Json<CreateArticleRequest>) -> impl Responder {
    // req is already validated and deserialized
    HttpResponse::Created().json(req.into_inner())
}

4. Implement JWT Authentication

Add JWT support:

jsonwebtoken = "9"
use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
use serde::{Deserialize, Serialize};


#[derive(Debug, Serialize, Deserialize)]
pub struct Claims {
    pub sub: String,
    pub exp: usize,
}


pub fn create_jwt(user_id: &str) -> Result<String, jsonwebtoken::errors::Error> {
    let claims = Claims {
        sub: user_id.to_string(),
        exp: 10000000000,
    };
    encode(
        &Header::default(),
        &claims,
        &EncodingKey::from_secret(b"secret"),
    )
}


pub fn verify_jwt(token: &str) -> Result<Claims, jsonwebtoken::errors::Error> {
    decode::<Claims>(
        token,
        &DecodingKey::from_secret(b"secret"),
        &Validation::default(),
    )
    .map(|c| c.claims)
}

5. Use Environment Variables for Secrets

Never hardcode secrets:

let jwt_secret = std::env::var("JWT_SECRET").expect("JWT_SECRET not set");
let api_key = std::env::var("API_KEY").expect("API_KEY not set");

6. Implement Rate Limiting

Add request rate limiting:

actix-governor = "0.2"
use actix_governor::{Governor, KeyExtractor};


HttpServer::new(|| {
    App::new()
        .wrap(Governor::default())
        // ... rest of your app
})

7. Enable Logging for Audit Trail

Configure structured logging:

use log::{info, warn, error};


#[post("/articles")]
async fn create_article(req: web::Json<Article>) -> impl Responder {
    info!("Creating article: {:?}", req.title);
    // ... rest of handler
}

Monitoring and Logging

Health Check Endpoint

Add a health check route for monitoring:

async fn health_check() -> impl Responder {
    HttpResponse::Ok().json(serde_json::json!({
        "status": "healthy",
        "timestamp": chrono::Utc::now().to_rfc3339()
    }))
}


app.route("/health", web::get().to(health_check))

Logging Configuration

Configure logging in your application:

use env_logger::Env;


#[actix_web::main]
async fn main() -> std::io::Result<()> {
    env_logger::Builder::from_env(Env::default().default_filter_or("info")).init();


    // ... rest of your app
}

Application Performance Monitoring

Integrate with monitoring services:

prometheus = "0.13"
use prometheus::{Counter, Histogram, Registry};
use std::sync::Mutex;


pub struct Metrics {
    pub http_requests_total: Counter,
    pub http_request_duration_seconds: Histogram,
}


impl Metrics {
    pub fn new() -> Self {
        let registry = Registry::new();


        Self {
            http_requests_total: Counter::new("http_requests_total", "Total HTTP requests").unwrap(),
            http_request_duration_seconds: Histogram::new("http_request_duration_seconds", "HTTP request duration").unwrap(),
        }
    }
}

Custom Domains

To use a custom domain with your Actix app on Klutch.sh:

  1. Access the app settings in your Klutch.sh dashboard

  2. Navigate to the “Domains” section

  3. Add your custom domain (e.g., example.com)

  4. Update your DNS records at your domain registrar:

    Create a CNAME record pointing to example-app.klutch.sh

    Name: www
    Type: CNAME
    Value: example-app.klutch.sh

  5. Wait for DNS propagation (usually 5-30 minutes)

  6. Verify the domain in Klutch.sh

Your app will be accessible at www.example.com.

Troubleshooting

1. App Won’t Start - Cargo Build Errors

Problem: Deployment fails with “error: could not compile my-actix-app”

Solution:

  • Ensure Cargo.toml and Cargo.lock are committed to Git
  • Run cargo build --release locally to verify the build works
  • Check for platform-specific dependencies that need to be in a Dockerfile
  • Verify all feature flags are correct in your dependencies

2. Database Connection Failures

Problem: Application crashes with “connection refused” or “failed to connect to database”

Solution:

  • Verify DATABASE_URL is set correctly with proper credentials and host
  • Ensure the database is accessible from the application container
  • Test the connection string locally: sqlx database create
  • Check database firewall rules allow connections from Klutch.sh
  • Add retry logic to your database connection code

3. Port Binding Issues

Problem: Application fails with “address already in use” or “permission denied”

Solution:

  • Ensure your app binds to 0.0.0.0 instead of 127.0.0.1
  • Verify the PORT environment variable is set to 8000 or your chosen port
  • Check that your Dockerfile or Nixpacks config exposes the correct port
  • Confirm the internal port in Klutch.sh matches your application (8000 is recommended)

4. Out of Memory (OOM) Errors

Problem: Application crashes with “Killed” or memory-related errors

Solution:

  • Optimize your release build with aggressive optimizations in Cargo.toml:

    [profile.release]
    opt-level = "z"
    lto = true
    codegen-units = 1
    strip = true

  • Reduce initial pool sizes for database connections

  • Monitor memory usage with a smaller compute tier first

  • Use async patterns to avoid spawning too many tasks

5. Slow Build Times

Problem: Deployment takes longer than expected during the build phase

Solution:

  • Create a Dockerfile with multi-stage builds for faster iterations
  • Cache cargo build layer: build dependencies separately before copying source
  • Use --release flag for optimized but slower builds
  • Consider using cargo-build-cache or Docker layer caching
  • Check if you have feature-heavy dependencies that could be simplified

Best Practices for Actix on Klutch.sh

  1. Use connection pooling for databases - SQLx provides pooling out of the box. Configure pool size based on your concurrency needs.

  2. Implement graceful shutdown - Handle SIGTERM signals to allow in-flight requests to complete before shutdown.

  3. Use structured logging - JSON-formatted logs make debugging and monitoring easier in production environments.

  4. Leverage async/await throughout - Actix’s strength is handling thousands of concurrent connections efficiently.

  5. Monitor performance metrics - Track response times, error rates, and resource usage to identify bottlenecks.

  6. Use request/response compression - Enable gzip compression for API responses to reduce bandwidth usage.

  7. Implement request validation - Use Serde’s validation features to catch invalid data early.

  8. Cache frequently accessed data - Use Redis for session data, frequently queried entities, and computed results.

  9. Test async code thoroughly - Use tokio::test for testing async functions and ensure no deadlocks occur.

  10. Keep dependencies up to date - Regularly update Actix and other crates to benefit from performance improvements and security patches.

External Resources