Skip to content
Klutch.sh Docs

Deploying an MSSQL App

Introduction

Microsoft SQL Server (MSSQL) is a relational database widely used for transactional and analytics workloads. Deploying MSSQL with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for data files—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample connection code, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your MSSQL Dockerfile/config (GitHub is the only supported git source)
  • Docker familiarity
  • Storage for database files and backups

For platform onboarding, see the Quick Start.

Architecture and ports

  • MSSQL listens on TCP port 1433; set the internal container port to 1433 and choose TCP traffic in Klutch.sh.
  • Persistent storage is required for /var/opt/mssql to retain databases and logs.
  • Only expose the SQL port you need; restrict network access appropriately.

Repository layout

mssql/
├── Dockerfile              # Must be at repo root for auto-detection
├── scripts/                # Optional init scripts
├── README.md
└── .env.example            # Template only; no secrets

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Test MSSQL locally before pushing to GitHub:

Terminal window
docker run --rm -p 1433:1433 \
  -e ACCEPT_EULA=Y \
  -e SA_PASSWORD="StrongPassw0rd!" \
  -v $(pwd)/data:/var/opt/mssql \
  mcr.microsoft.com/mssql/server:2022-latest

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec /opt/mssql/bin/sqlservr

Make it executable with chmod +x start.sh.

Dockerfile for MSSQL (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM mcr.microsoft.com/mssql/server:2022-latest


WORKDIR /app


# Copy optional init scripts
COPY scripts /app/scripts


EXPOSE 1433
CMD ["/opt/mssql/bin/sqlservr"]

Notes:

  • Pin the image tag for reproducible builds.
  • Ensure SA_PASSWORD meets MSSQL complexity requirements.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=1433
  • ACCEPT_EULA=Y
  • SA_PASSWORD=<StrongPassw0rd!>
  • MSSQL_PID=Developer (or Standard/Enterprise if licensed)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo MSSQL uses prebuilt image"
  • NIXPACKS_START_CMD=/opt/mssql/bin/sqlservr
  • NIXPACKS_JDK_VERSION=17 (not required for MSSQL itself, but listed for completeness)

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/opt/mssql — required for database files and transaction logs.

Ensure this path is writable inside the container.

Deploy MSSQL on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose TCP traffic for MSSQL.
  3. Set the internal port to 1433.
  4. Add the environment variables above (EULA, SA password, PID, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach a persistent volume for /var/opt/mssql, selecting a size that fits your data and log growth.
  6. Deploy. Your MSSQL endpoint will be reachable at example-app.klutch.sh:8000 over TCP for clients.

Sample code (Node.js connection)

import sql from "mssql";


const config = {
  user: "sa",
  password: "StrongPassw0rd!",
  server: "example-app.klutch.sh",
  port: 8000,
  database: "master",
  options: { encrypt: false },
};


const pool = await sql.connect(config);
const result = await pool.request().query("SELECT name FROM sys.databases");
console.log(result.recordset);
await pool.close();

Health checks and production tips

  • Use a simple query (e.g., SELECT 1) via your monitoring agent for health checks.
  • Enforce strong passwords and rotate credentials; store them only in Klutch.sh secrets.
  • Monitor disk usage on /var/opt/mssql and resize volumes before they fill.
  • Pin image tags and apply updates intentionally.
  • Configure backups externally; do not rely solely on container storage.

MSSQL on Klutch.sh combines reproducible Docker builds with managed secrets, durable volumes for data, and flexible TCP routing. With the Dockerfile at the repo root and port 1433 configured, you can run SQL Server reliably without extra YAML or workflow overhead.