Skip to content
Klutch.sh Docs

Deploying a Hapi App

Hapi is a powerful, enterprise-grade web framework for Node.js that emphasizes security, reliability, and developer experience. With its comprehensive plugin system, built-in request validation, authentication mechanisms, and flexible routing, Hapi is the ideal choice for building robust APIs, microservices, and web applications that demand high standards of code quality and maintainability. Organizations worldwide rely on Hapi for mission-critical applications.

This comprehensive guide walks you through deploying a Hapi application to Klutch.sh, covering both automatic Nixpacks-based deployments and Docker-based deployments. You’ll learn installation steps, explore sample code, configure environment variables, and discover best practices for production deployments.

Table of Contents

  • Prerequisites
  • Getting Started: Install Hapi
  • Sample Code Examples
  • Project Structure
  • Deploying Without a Dockerfile (Nixpacks)
  • Deploying With a Dockerfile
  • Environment Variables & Configuration
  • Plugins & Performance Optimization
  • Troubleshooting
  • Resources

Prerequisites

To deploy a Hapi application on Klutch.sh, ensure you have:

  • Node.js 18 or higher - Hapi requires a modern Node.js version for optimal performance
  • npm or yarn - For managing dependencies
  • Git - For version control
  • GitHub account - Klutch.sh integrates with GitHub for continuous deployments
  • Klutch.sh account - Sign up for free

Getting Started: Install Hapi

Create a New Hapi Project

Follow these steps to create and set up a new Hapi application:

  1. Create a new directory for your project and initialize npm:
    Terminal window
    mkdir my-hapi-app
    cd my-hapi-app
    npm init -y
  2. Install Hapi and development dependencies:
    Terminal window
    npm install @hapi/hapi
    npm install --save-dev nodemon

    The nodemon package helps with development by automatically restarting your server when files change.

  3. Create a basic Hapi server. Create a file called `index.js`: 
    const Hapi = require('@hapi/hapi');
    

    const port = process.env.PORT || 3000;
    const host = process.env.HOST || '0.0.0.0';
    

    const init = async () => {
      const server = Hapi.server({
        port,
        host,
        routes: {
          cors: true
        }
      });
    

      server.route({
        method: 'GET',
        path: '/',
        handler: (request, h) => {
          return { message: 'Hello from Hapi on Klutch.sh!' };
        }
      });
    

      server.route({
        method: 'GET',
        path: '/health',
        handler: (request, h) => {
          return {
            status: 'healthy',
            timestamp: new Date().toISOString(),
            uptime: process.uptime()
          };
        }
      });
    

      await server.start();
      console.log(`Server running at ${server.info.uri}`);
    };
    

    init().catch((err) => {
      console.error(err);
      process.exit(1);
    });
  4. Update your `package.json` with startup scripts: 
    {
      "name": "my-hapi-app",
      "version": "1.0.0",
      "description": "Hapi app deployed on Klutch.sh",
      "main": "index.js",
      "scripts": {
        "start": "node index.js",
        "dev": "nodemon index.js"
      },
      "dependencies": {
        "@hapi/hapi": "^21.0.0"
      },
      "devDependencies": {
        "nodemon": "^3.0.1"
      }
    }
  5. Test your app locally:
    Terminal window
    npm run dev

    Visit http://localhost:3000 to see your app running. Check the health endpoint at http://localhost:3000/health.

Sample Code Examples

Hapi Server with Multiple Routes and Request Validation

Here’s a complete example with multiple routes, input validation, and error handling:

const Hapi = require('@hapi/hapi');
const Joi = require('@hapi/joi');


const init = async () => {
  const server = Hapi.server({
    port: process.env.PORT || 3000,
    host: '0.0.0.0',
    routes: {
      cors: { origin: ['*'] },
      validate: {
        failAction: async (request, h, err) => {
          console.error(err);
          throw err;
        }
      }
    }
  });


  server.route({
    method: 'GET',
    path: '/',
    handler: (request, h) => {
      return { message: 'Welcome to Hapi on Klutch.sh!' };
    }
  });


  server.route({
    method: 'GET',
    path: '/api/users/{id}',
    options: {
      validate: {
        params: Joi.object({
          id: Joi.number().integer().required()
        })
      }
    },
    handler: (request, h) => {
      const { id } = request.params;
      return {
        id,
        name: 'John Doe',
        email: 'john@example.com'
      };
    }
  });


  server.route({
    method: 'POST',
    path: '/api/users',
    options: {
      validate: {
        payload: Joi.object({
          name: Joi.string().required(),
          email: Joi.string().email().required()
        })
      }
    },
    handler: (request, h) => {
      const { name, email } = request.payload;
      return {
        id: Math.floor(Math.random() * 10000),
        name,
        email,
        created: new Date().toISOString()
      };
    }
  });


  await server.start();
  console.log(`Server running at ${server.info.uri}`);
};


init().catch((err) => {
  console.error(err);
  process.exit(1);
});

Hapi with Plugins

const Hapi = require('@hapi/hapi');


const init = async () => {
  const server = Hapi.server({
    port: process.env.PORT || 3000,
    host: '0.0.0.0'
  });


  // Register plugins
  await server.register([
    {
      plugin: require('@hapi/basic'),
      routes: { prefix: '/api' }
    }
  ]);


  // Define custom plugin
  const routes = {
    plugin: {
      name: 'routes',
      version: '1.0.0',
      register: async function(server, options) {
        server.route({
          method: 'GET',
          path: '/version',
          handler: (request, h) => {
            return { version: '1.0.0' };
          }
        });
      }
    }
  };


  await server.register(routes);
  await server.start();
  console.log(`Server running at ${server.info.uri}`);
};


init().catch((err) => {
  console.error(err);
  process.exit(1);
});

Hapi with Database Connection and Caching

const Hapi = require('@hapi/hapi');


const init = async () => {
  const server = Hapi.server({
    port: process.env.PORT || 3000,
    host: '0.0.0.0',
    cache: [
      {
        name: 'memory',
        provider: {
          constructor: require('@hapi/catbox-memory')
        }
      }
    ]
  });


  // Decorate server with database connection
  server.decorate('server', 'db', {
    query: async (sql) => {
      // Your database query logic
      return [];
    }
  });


  server.route({
    method: 'GET',
    path: '/api/data',
    options: {
      cache: { expiresIn: 1000 * 60 * 5 } // 5 minutes
    },
    handler: async (request, h) => {
      const data = await server.db.query('SELECT * FROM data');
      return { data };
    }
  });


  await server.start();
  console.log(`Server running at ${server.info.uri}`);
};


init().catch((err) => {
  console.error(err);
  process.exit(1);
});

Project Structure

A typical Hapi project has this structure:

my-hapi-app/
├── node_modules/
├── routes/                 # Route handlers
│   ├── index.js
│   ├── api.js
│   └── users.js
├── plugins/                # Custom plugins
│   ├── database.js
│   └── authentication.js
├── utils/                  # Utility functions
│   ├── validators.js
│   └── logger.js
├── .env                    # Environment variables (not committed)
├── .gitignore
├── index.js               # Main application file
├── package.json
└── package-lock.json

Deploying Without a Dockerfile

Klutch.sh uses Nixpacks to automatically detect and build your Hapi application. This is the simplest deployment option that requires no additional configuration files.

  1. Push your Hapi application to a GitHub repository with all your source code, `package.json`, and `package-lock.json` files.
  2. Log in to your Klutch.sh dashboard.
  3. Create a new project and give it a name (e.g., "My Hapi API").
  4. Create a new app with the following configuration:
    • Repository - Select your Hapi GitHub repository and the branch to deploy
    • Traffic Type - Select HTTP (for web applications serving HTTP traffic)
    • Internal Port - Set to 3000 (the default port for Hapi applications)
    • Region - Choose your preferred region for deployment
    • Compute - Select the appropriate compute resource size
    • Instances - Choose how many instances to run (start with 1 for testing)
    • Environment Variables - Add any environment variables your app needs (database URLs, API keys, secrets, etc.)

    If you need to customize the start command or build process, you can set Nixpacks environment variables:

    • START_COMMAND: Override the default start command (e.g., node index.js)
    • BUILD_COMMAND: Override the default build command
  5. Click "Create" to deploy. Klutch.sh will automatically detect your Node.js project, install dependencies, and start your Hapi application.
  6. Once deployed, your app will be available at a URL like `example-app.klutch.sh`. Test it by visiting the URL in your browser and checking the health endpoint at `/health`.

Deploying With a Dockerfile

If you prefer more control over the build and runtime environment, you can use a Dockerfile. Klutch.sh will automatically detect and use any Dockerfile in your repository’s root directory.

  1. Create a `Dockerfile` in your project root: 
    # Multi-stage build for optimized Hapi deployment
    FROM node:18-alpine AS builder
    

    WORKDIR /app
    

    # Copy package files
    COPY package*.json ./
    

    # Install dependencies
    RUN npm ci
    

    # Production stage
    FROM node:18-alpine
    

    WORKDIR /app
    

    # Copy built dependencies from builder
    COPY --from=builder /app/node_modules ./node_modules
    COPY --from=builder /app/package*.json ./
    

    # Copy application code
    COPY . .
    

    # Set production environment
    ENV NODE_ENV=production
    

    # Expose port (must match your app's listening port)
    EXPOSE 3000
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
      CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"
    

    # Start the application
    CMD ["npm", "start"]
  2. Create a `.dockerignore` file to exclude unnecessary files from the Docker build: 
    node_modules
    npm-debug.log
    dist
    build
    .git
    .gitignore
    README.md
    .env
    .env.local
    .vscode
    .idea
    .DS_Store
  3. Push your code (with Dockerfile and .dockerignore) to GitHub.
  4. Follow the same deployment steps as the Nixpacks method:
    • Log in to Klutch.sh
    • Create a new project
    • Create a new app pointing to your GitHub repository
    • Set the traffic type to HTTP and internal port to 3000
    • Add any required environment variables
    • Click “Create”

    Klutch.sh will automatically detect your Dockerfile and use it to build and deploy your application.

  5. Your deployed app will be available at `example-app.klutch.sh` once the build and deployment complete.

Environment Variables & Configuration

Hapi applications can use environment variables for configuration. Set these in the Klutch.sh dashboard during app creation or update them afterward.

Common Environment Variables

# Server configuration
PORT=3000
HOST=0.0.0.0
NODE_ENV=production


# Database connection
DATABASE_URL=postgresql://user:password@db.example.com:5432/mydb


# API Keys and Secrets
API_KEY=your_api_key_here
SECRET_KEY=your_secret_key_here
JWT_SECRET=your_jwt_secret_here


# CORS configuration
CORS_ORIGIN=https://yourdomain.com


# Application settings
LOG_LEVEL=info
DEBUG=false

Using Environment Variables in Your App

const Hapi = require('@hapi/hapi');


const init = async () => {
  const port = process.env.PORT || 3000;
  const host = process.env.HOST || '0.0.0.0';
  const nodeEnv = process.env.NODE_ENV || 'development';
  const jwtSecret = process.env.JWT_SECRET;


  const server = Hapi.server({
    port,
    host,
    routes: {
      cors: process.env.CORS_ORIGIN ? { origin: [process.env.CORS_ORIGIN] } : true
    }
  });


  server.route({
    method: 'GET',
    path: '/config',
    handler: (request, h) => {
      return {
        environment: nodeEnv,
        hasJwtSecret: !!jwtSecret,
        port: port
      };
    }
  });


  await server.start();
  console.log(`Server running in ${nodeEnv} mode at ${server.info.uri}`);
};


init().catch((err) => {
  console.error(err);
  process.exit(1);
});

Customizing Build and Start Commands with Nixpacks

If using Nixpacks deployment without a Dockerfile, you can customize build and start commands by setting environment variables:

BUILD_COMMAND: npm run build
START_COMMAND: npm start

Set these as environment variables during app creation on Klutch.sh.

Plugins & Performance Optimization

Hapi’s plugin ecosystem provides powerful extensions for common functionality:

const Hapi = require('@hapi/hapi');


const init = async () => {
  const server = Hapi.server({
    port: process.env.PORT || 3000,
    host: '0.0.0.0'
  });


  // Register plugins
  await server.register([
    {
      plugin: require('@hapi/cors'),
      options: {
        origin: ['*']
      }
    },
    {
      plugin: require('@hapi/jwt'),
      options: {
        keys: process.env.JWT_SECRET || 'your-secret-key'
      }
    },
    {
      plugin: require('@hapi/basic')
    },
    {
      plugin: require('@hapi/inert') // Static file serving
    }
  ]);


  await server.start();
  console.log(`Server running at ${server.info.uri}`);
};


init().catch((err) => {
  console.error(err);
  process.exit(1);
});

Horizontal Scaling

Klutch.sh makes it easy to scale your Hapi application:

  • Multiple Instances - Set the number of instances in the app configuration to distribute traffic across multiple containers
  • Load Balancing - Klutch.sh automatically load balances traffic across all instances
  • Stateless Design - Ensure your application is stateless so it can run on multiple instances
  • Shared Resources - Use external services (Redis, databases) for shared state across instances

Performance Optimization Tips

  1. Request Validation - Use Hapi’s built-in Joi validation to catch errors early
  2. Caching - Implement route caching for frequently accessed endpoints
  3. Connection Pooling - Use connection pools for database connections to manage resources efficiently
  4. Async/Await - Use async/await properly to handle non-blocking operations
  5. Compression - Enable payload compression for API responses
  6. Logging - Configure appropriate log levels to avoid performance impact

Example with optimizations:

const Hapi = require('@hapi/hapi');


const init = async () => {
  const server = Hapi.server({
    port: process.env.PORT || 3000,
    host: '0.0.0.0',
    routes: {
      payload: {
        compress: true
      }
    },
    cache: [
      {
        name: 'memory',
        provider: {
          constructor: require('@hapi/catbox-memory')
        }
      }
    ]
  });


  // Cached route
  server.route({
    method: 'GET',
    path: '/api/cached-data',
    options: {
      cache: { expiresIn: 1000 * 60 * 5 } // 5 minutes
    },
    handler: async (request, h) => {
      return { data: 'cached content' };
    }
  });


  await server.start();
  console.log(`Server running at ${server.info.uri}`);
};


init().catch((err) => {
  console.error(err);
  process.exit(1);
});

Troubleshooting

Application Won’t Start

Problem - Deployment completes but the app shows as unhealthy

Solution:

  • Check that your app listens on port 3000 (or the port you specified)
  • Verify that process.env.PORT is properly used in your code
  • Ensure the start script in package.json correctly starts your app
  • Check application logs in the Klutch.sh dashboard for error messages
  • Verify that host is set to 0.0.0.0 instead of localhost

Build Fails with “Cannot find module”

Problem - Dependencies are not installed during build

Solution:

  • Ensure your package.json is in the root directory
  • Verify all dependencies are listed in dependencies, not just devDependencies
  • Check that dependency names are spelled correctly
  • Ensure package-lock.json exists and is up to date

Port Already in Use

Problem - Error about port 3000 already being in use

Solution:

  • Make sure only one instance of your app is running
  • Check that previous processes are properly terminated
  • Verify the PORT environment variable is being used correctly

High Memory Usage

Problem - App uses excessive memory and gets killed

Solution:

  • Check for memory leaks in your application code
  • Implement proper cleanup for connections and event listeners
  • Monitor memory usage during development with the --inspect flag
  • Consider increasing the compute tier or number of instances

Slow Response Times

Problem - Requests are responding slowly despite Hapi’s performance

Solution:

  • Check for synchronous operations that should be async
  • Implement caching for frequently accessed data
  • Enable compression for responses
  • Profile your application to identify bottlenecks
  • Consider upgrading your compute tier

Resources

Summary

Deploying a Hapi application on Klutch.sh is straightforward whether you choose Nixpacks or Docker. Both methods provide reliable, scalable hosting for your robust APIs and web applications. Start with Nixpacks for simplicity and quick deployments, or use Docker for more control over your build environment. With Klutch.sh’s easy scaling, automatic load balancing, and environment variable management, you can deploy your Hapi app from development to production and scale it to handle enterprise-grade workloads with ease.