Introduction:

In this tutorial, I will walk you through setting up HackMD with GitHub authentication using Podman, PostgreSQL, Nginx, and Certbot.

HackMD is a powerful real-time, multi-platform collaborative markdown note editor, perfect for teams to work together on documentation, notes, data collection, and more. We’ll be using Red Hat’s PostgreSQL image for the database and configuring SSL with Certbot for secure communication.

Setting up PostgreSQL with Red Hat Image

First, we’ll set up the PostgreSQL database using the Red Hat PostgreSQL image.

• Login to Red Hat’s container registry:

podman login registry.redhat.io -u 

• Pull the PostgreSQL image:

podman pull registry.redhat.io/rhel8/postgresql-10@sha256:b377e15891995aa9c778ddc38f44c9635d04771cf77ac90fcd38a5a684326d82

• Stop and remove any existing PostgreSQL container (if there is any, I am using this name, so for multiple run I am running this command, you can skip this)

podman stop hackmd_postgres
podman rm hackmd_postgres

• Create a directory to store PostgreSQL data and assign permissions. We use SELinux to enhance the security, the chcon command is used to change the SELinux context of a file or a directory:

#For data persistence I am creating this folder, there are different way you can achieve this
sudo mkdir -p /root/hackmd/postgres 
sudo chcon -Rt container_file_t /root/hackmd/postgres

Create a new Pod for your PostgreSQL and HackMD services:

podman pod create --name hackmd_pod -p 8000:3000

Run the PostgreSQL container in the Pod:

podman run -d --pod hackmd_pod --name hackmd_postgres 
    --restart always 
    -e POSTGRESQL_USER=hackmd 
    -e POSTGRESQL_PASSWORD=SupSecret 
    -e POSTGRESQL_DATABASE=hackmd 
    -v /root/hackmd/postgres:/var/lib/pgsql/data 
    registry.redhat.io/rhel8/postgresql-10@sha256:b377e15891995aa9c778ddc38f44c9635d04771cf77ac90fcd38a5a684326d82

Setting up GitHub OAuth for HackMD

Before setting up the HackMD application, we need to configure GitHub OAuth.

• Navigate to the settings of your GitHub account and select “OAuth Apps” under “Developer settings”.

• Click on “New OAuth App”. Provide the necessary details.
• Set the “Authorization callback URL” as https://hackmd.your-domain.com/auth/github/callback. Replace hackmd.your-domain.com with your actual domain name.
  

After creating the app, GitHub provides you with a Client ID and a Client Secret. Note them down.

Setting up HackMD with GitHub OAuth

• Stop and remove any existing HackMD container (optional, skip this if not required)

podman stop hackmd
podman rm hackmd

Run the HackMD container in the Pod:

podman run -d --pod hackmd_pod --name hackmd 
    --restart always 
    -e CMD_DB_URL=postgres://hackmd:SupSecret@localhost/hackmd 
    -e CMD_GITHUB_CLIENTID= 
    -e CMD_GITHUB_CLIENTSECRET= 
    -e CMD_ALLOW_EMAIL_REGISTER=false 
    -e CMD_GITHUB_ALLOW_AUTO_REGISTER=true 
    -e CMD_GITHUB_CALLBACK_URL='https://hackmd.your-domain.com/auth/github/callback' 
    -e CMD_DOMAIN='hackmd.your-domain.com' 
    -e CMD_PROTOCOL_USESSL=true 
    -e CMD_URL_ADDPORT=false 
    -v /root/hackmd/app/public/uploads:/home/hackmd/app/public/uploads 
    docker.io/hackmdio/hackmd:2.4.2-cjk

Replace and with the actual values you got from GitHub.

Setting up Nginx

• Install Nginx:

sudo yum install nginx -y

• Start and enable Nginx:

sudo systemctl start nginx
sudo systemctl enable nginx

• Configure Nginx to reverse proxy to your HackMD service. Edit the Nginx configuration file for your domain:

sudo vim /etc/nginx/conf.d/hackmd.your-domain.com.conf

• Add the following content to the file:

server {
    listen 80;
    server_name hackmd.your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Replace hackmd.your-domain.com with your actual domain name. Save and close the file.

• Test the Nginx configuration:

sudo nginx -t

If the test is successful, reload Nginx to apply the changes:

sudo systemctl reload nginx

Configuring SSL with Certbot

Let’s Encrypt is a free, automated, and open certificate authority brought to you by the nonprofit Internet Security Research Group (ISRG). Certbot is a client that makes getting and renewing these certificates very easy.

• Install Certbot:

sudo yum install certbot python3-certbot-nginx -y

• Obtain and Install a certificate:

sudo certbot --nginx -d hackmd.your-domain.c