Coolify has emerged as a premier self-hosted alternative to Vercel and Netlify. While its default Nixpacks builder is excellent for zero-configuration deployments, developers often require granular control over the build environment.

This guide demonstrates how to deploy a Next.js application on Coolify v4 (specifically tested on v4.0.0-beta.460) using a multi-stage Dockerfile. This method ensures a highly optimized, production-ready image.

Prerequisites

• A running instance of Coolify v4 (Self-hosted).
• A Next.js project pushed to a Git repository (GitHub, GitLab, etc.).

Step 1: Optimize Next.js for Docker

The most critical step before configuring the container is setting up Next.js to create a standalone build. This feature automatically traces your import dependencies and creates a smaller deployment folder, eliminating the need to copy the entire node_modules directory into your final image.

Open your next.config.js file and add the output: 'standalone' configuration:

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
};

module.exports = nextConfig;

Step 2: Create the Multi-Stage Dockerfile

Create a file named Dockerfile in the root of your project. We will use a multi-stage build strategy to keep the final image lightweight. This process splits the build into three stages: 1. Deps: Installs dependencies (cached for speed). 2. Builder: Compiles the Next.js application. 3. Runner: The final, minimal production image.

Copy the following code into your Dockerfile:

Dockerfile

# Stage 1: Install dependencies
FROM node:18-alpine AS deps
WORKDIR /app
# Install libc6-compat (needed for some native dependencies)
RUN apk add --no-cache libc6-compat
COPY package.json package-lock.json* ./
RUN npm ci

# Stage 2: Build the application
FROM node:18-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# Disable Next.js telemetry during build
ENV NEXT_TELEMETRY_DISABLED 1
RUN npm run build

# Stage 3: Production runner
FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

# Create a system user for security
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# Copy the standalone build and static assets
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT 3000
CMD ["node", "server.js"]

Note: Create a .dockerignore file in your root directory and add node_modules and .next to it. This prevents local build files from slowing down the Docker build context.

Step 3: Configure the Project in Coolify

1. Log in to your Coolify dashboard.
2. Click + New Resource and select Public Repository (or Private Repository if you have configured GitHub App access).
3. Paste your repository URL and select the branch you wish to deploy (usually main).
4. Under Build Pack, select Dockerfile.
   • Coolify defaults to Nixpacks, so this manual selection is crucial.
5. Click Continue.

Step 4: Define Environment Variables

If your Next.js application relies on environment variables (like DATABASE_URL or API_KEY), you must define them in Coolify before deploying.

1. Navigate to the Environment Variables tab in your project view.
2. Add your keys and values.
3. Ensure you do not commit a .env file to your Git repository; managing them inside Coolify is more secure.

Step 5: Deploy

1. Go back to the Configuration tab.
2. Verify the Ports Exposes setting is set to 3000 (matching the EXPOSE instruction in our Dockerfile).
3. Click Deploy in the top right corner.

Coolify will now pull your code, build the Docker image using the stages defined in Step 2, and start the container. You can view the build logs in real-time to monitor the progress. Once the status changes to Running, your optimized Next.js application is live.

WriteFreely is beloved for its minimalism. However, fostering a community often requires a feedback loop. The challenge is adding comments without shattering that clean, distraction-free aesthetic. I recently integrated Cusdis—a lightweight, open-source, and privacy-friendly comment system—into this blog. It aligns seamlessly with WriteFreely’s ethos: it requires no user tracking and adapts beautifully with a bit of custom CSS.

Here is how to implement a fully dynamic, styled comment section. This script ensures the widget loads only on individual posts (keeping your homepage pristine) and automatically respects dark mode.

Step 1: Get Your Cusdis ID

First, you need a running Cusdis instance. You have two paths:

• Cloud: Create a free account at Cusdis.com.
• Self-Hosted: Host it yourself on a VPS (using Coolify or Docker) for 100% data ownership.

Once you have access to your dashboard, copy your App ID (e.g., f42fd160-a4f2-...). You will need this for the JavaScript configuration below.

Step 2: The Logic (Why Custom JS?)

Since WriteFreely lacks native support for editing individual post templates, we cannot simply paste the standard Cusdis embed code. A static embed cannot automatically fetch the unique Page ID or Title for every article.

Instead, we use Custom JavaScript to:

1. Verify context: Check if the user is viewing a single post (ignoring the homepage).
2. Build the UI: Dynamically append a “Comments” container to the bottom of the article.
3. Inject the Widget: Initialize Cusdis with the correct metadata (ID, URL, Title).
4. Style: Force the widget into “Dark Mode” to match the theme.

Step 3: The JavaScript Code

Navigate to your WriteFreely dashboard, go to Customize > Custom JavaScript, and paste the code below.

Note: Be sure to replace 'YOUR-APP-ID-HERE' with the actual ID you copied in Step 1.

(function() {
    // Only run this script if we are on a post page (body#post)
    // This prevents the comments from loading on the homepage or collections.
    var postBody = document.querySelector('body#post');
    
    if (postBody) {
        // 1. Create the container div for Cusdis
        var cusdisContainer = document.createElement('div');
        cusdisContainer.id = 'cusdis_thread';
        cusdisContainer.dataset.host = '[https://cusdis.com](https://cusdis.com)';
        cusdisContainer.dataset.appId = 'YOUR-APP-ID-HERE'; // PASTE YOUR ID HERE
        cusdisContainer.dataset.pageId = window.location.pathname;
        cusdisContainer.dataset.pageUrl = window.location.href;
        cusdisContainer.dataset.pageTitle = document.title;
        cusdisContainer.dataset.theme = 'dark'; // Forces dark mode

        // 2. Append the container to the article or main content area
        // Note: 'article' is standard in most WriteFreely themes. 
        var article = document.querySelector('article');
        if (article) {
            article.appendChild(cusdisContainer);
        }

        // 3. Load the Cusdis SDK asynchronously
        var script = document.createElement('script');
        script.src = '[https://cusdis.com/js/cusdis.es.js](https://cusdis.com/js/cusdis.es.js)';
        script.async = true;
        script.defer = true;
        document.body.appendChild(script);
    }
})();

Step 4: The styling

Now that the functionality is in place, let's style the container to look like a piece of retro-futuristic hardware. We want a monospace font, a “console” border, and a distinct separation from the rest of your content.

Navigate to Customize > Custom CSS and add the following:

/* --- VISIBILITY RULES of COMMENT SECTION --- */
body#collection #comment-section,
body#subpage #comment-section {
    display: none !important;
}

body#post #comment-section {
    display: block !important;
}

/* --- END VISIBILITY RULES OF COMMENT SECTION -- */
/* --- CUSDIS COMMENT SECTION FIXES --- */
#comment-section {
    margin-top: 3rem; /* space from article content */
    width: 100%;
    max-width: 100%;
}

/* Cusdis iframe container */
#cusdis_thread {
    width: 100% !important;
    min-height: 500px; /* initial height */
    border-radius: 8px;
    overflow: hidden; /* remove inner scrollbars */
    background-color: var(--surface-color) !important;
    border: 1px solid var(--border-color) !important;
    box-shadow: 0 0 15px rgba(0, 0, 0, 0.4);
}

/* Make the iframe responsive */
#cusdis_thread iframe {
    width: 100% !important;
    min-height: 500px !important;
    height: auto !important;
    border: none !important;
}

/* Dark theme for Cusdis content */
#cusdis_thread {
    --cusdis-background: var(--surface-color);
    --cusdis-text-color: var(--text-color);
    --cusdis-accent-color: var(--accent-color);
    --cusdis-border-color: var(--border-color);
    --cusdis-input-background: #222; /* input background */
    --cusdis-input-text-color: #eee; /* input text */
    --cusdis-button-background: var(--accent-color);
    --cusdis-button-text-color: #000;
}

/* Force Cusdis to expand to fit content (if Cusdis JS supports it) */
#cusdis_thread iframe {
    height: 100% !important;
}

/* Inputs and textareas */
#cusdis_thread textarea,
#cusdis_thread input {
    background-color: #222 !important;
    color: #eee !important;
    border: 1px solid var(--border-color) !important;
    border-radius: 6px;
    padding: 8px;
}

/* Submit button */
#cusdis_thread button {
    background-color: var(--accent-color) !important;
    color: #000 !important;
    font-weight: 700;
    border-radius: 6px !important;
    padding: 6px 14px !important;
    border: none !important;
    cursor: pointer;
    transition: all 0.2s ease;
}

#cusdis_thread button:hover {
    background-color: #3aa8d1 !important;
    box-shadow: 0 0 12px rgba(98, 200, 243, 0.5) !important;
    color: #000 !important;
}

/* Scrollbar styling for iframe if it still scrolls */
#cusdis_thread iframe::-webkit-scrollbar {
    width: 8px;
}

#cusdis_thread iframe::-webkit-scrollbar-thumb {
    background-color: #555;
    border-radius: 4px;
}

#cusdis_thread iframe::-webkit-scrollbar-track {
    background-color: #111;
}

/* Optional: smooth font for Cusdis */
#cusdis_thread,
#cusdis_thread iframe {
    font-family: 'Nunito', sans-serif !important;
}

Final Thoughts

And that is it. You now have a lightweight, privacy-respecting comment section that loads exclusively on your articles.

By injecting the widget via JavaScript, you bypass WriteFreely's template limitations while maintaining total control over the look and feel. Your readers can now interact with your content in a space that feels like a natural extension of your blog's “hacker” aesthetic—no tracking pixels attached.

I currently run a Coolify instance on my VPS and recently decided to host a lightweight blogging platform. I managed to deploy WriteFreely using the open-source algernon/writefreely Docker image. While the initial deployment was straightforward, configuring the storage and database correctly required some specific steps. Here is a walkthrough of how I achieved a stable setup.

1. The Docker Configuration

First, I pulled the Docker image and deployed it via Coolify. The primary challenge was configuring persistent storage. By default, if you restart the container, you lose your configuration, which makes the service unusable in production.

To address this, I configured Coolify to create a persistent volume. I mapped a volume named wf_data to /data inside the container. This step is critical because the config.ini file needs to reside in this directory to persist across restarts.

2. Adding a Standalone MySQL Database

I preferred not to use the default SQLite engine, so I decided to provision a standalone MySQL database service within Coolify. The process is remarkably straightforward: you simply create a new resource, select MySQL, and let Coolify handle the password generation.

The tricky part was establishing the connection between the app and the database. I initially encountered “Access Denied” errors because I was attempting to use the default mysql user. Once I updated the credentials in the configuration file to use the root user (or a dedicated user with proper permissions), the connection worked perfectly.

3. Linking the Components

To ensure WriteFreely correctly reads from the persistent volume, I had to modify the startup command. I couldn't immediately locate the command field in the UI, so I utilized the Docker Compose configuration to override the entry point:

/bin/sh -c "./writefreely -c /data/config.ini"

Additionally, I ran the configuration wizard directly inside the terminal to generate the initial config.ini. I made sure to point the encryption keys and database paths specifically to /data.

Conclusion

I now have a fully functional WriteFreely instance running on my VPS, complete with persistent storage and a robust MySQL backend. It is a highly efficient and self-contained setup.