step-by-step Docker deployment tutorial needed

Detailed Docker deployment steps

I used Happy, but my mobile client cannot display the returned content, while the CLI terminal runs normally after input.

I suspect it might be a network issue, so I tried Docker deployment, but it seems many components are missing.

I couldn't find relevant tutorials either. Could you provide a deployment guide: a step-by-step tutorial?

I fork Server and then created a docker image myself, right in github, and there is a docker compose sample file, but unfortunately after I configured the environment variables in the local CLI, after executing happy auth login --force, the phone scanned the code, and the phone already prompted that the authorization was successful. But the terminal keeps prompting to wait for authorization

I fork Server and then created a docker image myself, right in github, and there is a docker compose sample file, but unfortunately after I configured the environment variables in the local CLI, after executing happy auth login --force, the phone scanned the code, and the phone already prompted that the authorization was successful. But the terminal keeps prompting to wait for authorization

I used your version and it has been running successfully. I performed the following operations:
Local:

export HAPPY_SERVER_URL="https://your-domain"
export HAPPY_HOME_DIR="$HOME/.happy-selfhost"

On happy-server container npx prisma db push --schema=/app/node_modules/.prisma/client/schema.prisma

I fork Server and then created a docker image myself, right in github, and there is a docker compose sample file, but unfortunately after I configured the environment variables in the local CLI, after executing happy auth login --force, the phone scanned the code, and the phone already prompted that the authorization was successful. But the terminal keeps prompting to wait for authorization

I used your version and it has been running successfully. I performed the following operations: Local:

export HAPPY_SERVER_URL="https://your-domain"
export HAPPY_HOME_DIR="$HOME/.happy-selfhost"
On happy-server container npx prisma db push --schema=/app/node_modules/.prisma/client/schema.prisma

Are you experiencing any issues? Can the mobile phone scan the code for authorization?

I am having the same problem. I have followed the instructions to get the server working but when I happy auth login the mobile app says "Terminal connection successfully" but the CLI app says "Waiting for authentication..." and nothing happens.

And thank you so much for creating such amazing software, happy is an amazing addition to my workflow.

@YeautyYE

Hi everyone,

I've been looking at the Docker setup and wanted to share some observations that might help with the deployment and authentication issues.

About the docker-compose.yml

The compose file includes a dedicated migrate service that automatically runs:

npx prisma db push --schema=/app/node_modules/.prisma/client/schema.prisma

This should handle the database migration that @YeautyYE mentioned.

Sample docker-compose.yml

Here's a simplified version with all required services:

version: '3.8'

services:
  happy-server:
    image: happy-server:latest
    build:
      context: ./happy-server
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "3005:3005"
    environment:
      - NODE_ENV=production
      - PORT=3005
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=redis://redis:6379
      - HANDY_MASTER_SECRET=${HANDY_MASTER_SECRET}
      - HAPPY_SERVER_URL=${HAPPY_SERVER_URL}
      - S3_HOST=happy-minio
      - S3_PORT=9000
      - S3_USE_SSL=false
      - S3_ACCESS_KEY=${MINIO_ROOT_USER}
      - S3_SECRET_KEY=${MINIO_ROOT_PASSWORD}
      - S3_BUCKET=${S3_BUCKET}
      - S3_PUBLIC_URL=${S3_PUBLIC_URL}
    depends_on:
      - postgres
      - redis
      - happy-minio
      - migrate
      - minio-setup

  migrate:
    image: happy-server:latest
    command: npx prisma db push --schema=/app/node_modules/.prisma/client/schema.prisma
    environment:
      - DATABASE_URL=${DATABASE_URL}
    depends_on:
      - postgres
    restart: "no"

  postgres:
    image: postgres:15.4
    environment:
      - POSTGRES_DB=${POSTGRES_DB}
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  happy-minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - minio_data:/data
    command: server /data --console-address :9001

  minio-setup:
    image: minio/mc:latest
    depends_on:
      - happy-minio
    entrypoint: >
      /bin/sh -c "
      sleep 5;
      /usr/bin/mc alias set local http://happy-minio:9000 ${MINIO_ROOT_USER} ${MINIO_ROOT_PASSWORD};
      /usr/bin/mc mb local/${S3_BUCKET} --ignore-existing;
      /usr/bin/mc anonymous set download local/${S3_BUCKET};
      exit 0;
      "
    restart: "no"

volumes:
  postgres_data:
  redis_data:
  minio_data:

Environment Variables Needed

Create a .env file with:

DATABASE_URL=postgresql://postgres:yourpassword@postgres:5432/happy
POSTGRES_DB=happy
POSTGRES_USER=postgres
POSTGRES_PASSWORD=yourpassword
HANDY_MASTER_SECRET=your-secret
HAPPY_SERVER_URL=https://your-public-url
S3_BUCKET=happy
S3_PUBLIC_URL=https://your-public-minio-url
MINIO_ROOT_USER=your-minio-user
MINIO_ROOT_PASSWORD=your-minio-password

Security Note: Don't use the default minioadmin credentials for MinIO. Generate strong, unique credentials:
# Generate secure random credentials
openssl rand -base64 16  # for MINIO_ROOT_USER
openssl rand -base64 32  # for MINIO_ROOT_PASSWORD

Authentication Issue

The "mobile says connected but CLI waiting" problem is likely related to WebSocket/real-time communication. Make sure HAPPY_SERVER_URL is the publicly accessible URL that both your CLI and mobile client can reach.

Encountered the same problem, the phone shows scan successful, but the CLI keeps waiting

In the happy code (client side)
📍 Location: sources/sync/serverConfig.ts:7

const DEFAULT_SERVER_URL = 'https://api.cluster-fluster.com';

There is a hardcoded server address in the app, and no configuration option is provided. This should be the root cause.

To everyone here who is confused about how to set everything up, the issue is most likely not your setup on the server but on the app itself. When I figured this out I kicked myself.

For me the problem was that I didnt know that you need to fully log out in the APP and then on the QR sign in screen there is a button on the top right that allows you to enter a custom server URL.

I am betting that all of your setups are probably perfect or close to it and you are missing this one crucial step.

Easy way to test this is to use the webapp. If it works then you missed this step and you are VERY close.

In the happy code (client side) 📍 Location: sources/sync/serverConfig.ts:7

const DEFAULT_SERVER_URL = 'https://api.cluster-fluster.com';

There is a hardcoded server address in the app, and no configuration option is provided. This should be the root cause.

This is incorrect, there is a button there before you log in on the top right! If you cant find it ask Claude, thats how I ended up finding it.

@geekdada

In the happy code (client side) 📍 Location: sources/sync/serverConfig.ts:7在 happy 代码（客户端）中 📍 位置：sources/sync/serverConfig.ts:7
const DEFAULT_SERVER_URL = 'https://api.cluster-fluster.com';
There is a hardcoded server address in the app, and no configuration option is provided. This should be the root cause.应用程序中硬编码了一个服务器地址，并且没有提供配置选项。这应该是根本原因。

This is incorrect, there is a button there before you log in on the top right! If you cant find it ask Claude, thats how I ended up finding it.这是不正确的，在您登录右上角之前有一个按钮！如果您找不到它，可以问 Claude，我就是这样找到它的。

Great, I succeeded. I set up the server on a public VPS, successfully connected and authenticated on my phone, and tested the functionality—everything works normally (aside from Happy's own bugs).

I had imagined that the URL setting would be somewhere in the settings, but I never thought I’d need to log out to see the relevant button, and it wasn’t very noticeable.

Now it’s working properly. The Docker Compose provided by @geekdada is usable, and I added a Caddy reverse proxy on top of my service, applied a certificate for the domain, and it also works fine.

Thank you all,

However, the official documentation still needs to be updated. The actual required components differ significantly from the demo compose.yml provided by the official, with many essential components such as minio completely missing.

docs: update self-hosting guide with Docker Compose and MinIO setup

thank you!!!

attaching a screenshot of where the icons is on the mobile client. if you don't see it, force a new log-out.

Navigation Menu

Repository navigation

step-by-step Docker deployment tutorial needed #420

About the docker-compose.yml

Sample docker-compose.yml

Environment Variables Needed

Authentication Issue

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

step-by-step Docker deployment tutorial needed #420

Description

Activity

CherryLover commented on Oct 16, 2025

YeautyYE commented on Oct 17, 2025

CherryLover commented on Oct 23, 2025

cprepos commented on Nov 24, 2025

geekdada commented on Dec 21, 2025

About the docker-compose.yml

Sample docker-compose.yml

Environment Variables Needed

Authentication Issue

wulabing commented on Jan 12, 2026

wulabing commented on Jan 12, 2026

cprepos commented on Jan 12, 2026

cprepos commented on Jan 12, 2026

wulabing commented on Jan 13, 2026

wulabing commented on Jan 13, 2026

ruphy commented on Jan 21, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions