• Hosting your email server is the first step to secure your privacy

• It saves you money if you own multiple domains

What You'll Need

• [ ] Brand new VPS or any Linux Server (My recommended VPS provider is Linode)

• [ ] Ubuntu 22.04 LTS is the latest supported version

• [ ] SSH access with sudo privilege

Step 1: Create non-root user

To create a new user, please type the following:

adduser johndoe

Replace johndoe with your own username. Then follow the prompts to set the password and other details

We need to let the new user run commands with sudo when we need, so, to make that happen you'll need to run:

usermod -aG sudo johndoe

Then connect to the server using the new user.

ssh johndoe@YOUR-SERVER-IP

We have logged in using the password of our new user which is not secure. To prepare our future logins to use ssh keys instead of passwords, let's quickly do the following:

mkdir -p ~/.ssh    # to create .ssh folder
chmod 700 ~/.ssh   # set correct permissions
touch ~/.ssh/authorized_keys  # create file where we put our keys
chmod 600 ~/.ssh/authorized_keys # change file permissions

Let's open another terminal, if you don't have ssh keys in your computer and create new one by running:

ssh-keygen -t rsa -b 4096 -C youremail@example.com

Step 2: Setup and Secure Your Server

Before installing Mail-in-a-Box, it's crucial to properly secure your VPS. Let's lock down SSH access and configure the firewall to only allow necessary ports.

Disable Password Authentication for SSH

\==⚠️ Important: Ensure you've already set up SSH key authentication before disabling password login, or you'll lock yourself out of your server!==

Password-based SSH authentication is vulnerable to brute force attacks. Let's configure SSH to only accept key-based authentication:

# Edit the SSH configuration file
sudo nano /etc/ssh/sshd_config

Find and modify these settings (or add them if not present):

PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

Save the file and restart the SSH service:

sudo systemctl restart ssh

Configure Firewall to Allow Only Required Ports

Mail-in-a-Box needs specific ports open to function properly. Let's use UFW (Uncomplicated Firewall) to restrict access:

# install UFW if not already installed
sudo apt update && sudo apt install ufw -y

# set default policies
sudo ufw default deny incoming
sudo ufw default allow outgoing

# allow SSH (always do this first to avoid lockout)
sudo ufw allow 22/tcp

# allow essential Mail-in-a-Box ports
sudo ufw allow 25/tcp    # SMTP (mail delivery)
sudo ufw allow 587/tcp   # SMTP submission (outgoing mail)
sudo ufw allow 465/tcp   # SMTP over SSL (legacy secure mail)
sudo ufw allow 143/tcp   # IMAP
sudo ufw allow 993/tcp   # IMAP over SSL
sudo ufw allow 110/tcp   # POP3
sudo ufw allow 995/tcp   # POP3 over SSL
sudo ufw allow 80/tcp    # HTTP (for Let's Encrypt)
sudo ufw allow 443/tcp   # HTTPS (webmail and admin panel)

# Enable the firewall
sudo ufw enable

Verify your firewall configuration:

sudo ufw status verbose

You should see all the required ports listed as "ALLOW" in the output.

Step 2: Install Mail-in-a-Box

To install Mail-in-a-Box please run the following command:

curl -s https://mailinabox.email/setup.sh | sudo bash

Then follow the instructions shown in the instructions. You'll be asked to set your email. At first it will show us me@current-hostname so replace it with me@yourdomain.com, make sure to replace yourdomain.com with a domain name you control.

If you need to change later any of the answers you provided, you can run

sudo mailinabox

Step 3: Setup DNS & Domains

Go to your domain DNS dashboard, if you don't know how, please search "Godaddy DNS settings" replace with the name of Godaddy with the provider you use.

To find out what records to put in the DNS records. Go to box.yourdomain.com/admin then you'll see the rest of instructions by going to each menu and see places that have red error messages.

The most important places to check are the System, Mail & Users dropdown in the top nav-bar of the page.

Figer: 1

Some of the important subdomains you need to add in your domain name provider's DNS are the following:

Subdomain: leave it empty | | | | | | A/AAAA Record | box.example.com | IP Address: SERVER-IP | | | autoconfig.example.com | IP Address: SERVER-IP | | | autoconfig.box.example.com | IP Address: SERVER-IP | | | ns1.box.example.com | IP Address: SERVER-IP | | | | | | TXT Record | example.com | v=spf1 include:example.com include:box.example.com -all | | | _dmarc | v=DMARC1; p=quarantine; rua=mailto:info@example.com; pct=100; adkim=s; aspf=s | | | default._bimi | v=BIMI1;l=https://example.com/path/to/your/logo.svg;a= | | | s1._domainkey | Use Online Generator like easydmarc.com to create what to put here. | | | | |

The above TXT records are important to make your email messages legitimate, else they'll be rejected by spam filters and end up in Junk/Spam folder instead of the Inbox.

Under System dropdown click TLS (SSL) Certificates then click Provision button to generate those certificates. After this succeeds you'll see most of red warnings change to green.

Step 4: Add Email Users

To add a new domain you need to add the first email and this automatically saves the DNS records for the new domain name. Click on Mail and Users dropdown on the top nav-bar then click users. Fill the form.

Normal user can only login through the email portal which is box.example.com/mail but Administrator can login as email user and admin user in box.example.com/admin.

Testing Your Implementation

To find out if your email has an issue or is rejected by Gmail or Microsoft you'll receive rejected email notification to the email you have put in your DNS _dmarc record entry. If everything is working you'll be able to send emails to all providers.

To use your new emails in email apps use the Instructions menu under Mail & Users dropdown. That page lists all the ways you can use your emails on mobile and desktop apps.

Conclusion

• We have created our self-hosted email service

• We also secured our server

• And added extra TXT DNS entries to make our emails legitimate and avoid them to end up in spam box.

Further Resources

• Mail-in-a-Box Official Website

• Mail-in-a-Box Github Repository

AWS has a MySQL compatible database but it's expensive and sometimes the cost doesn't justify the convenience we get from having such a service for personal projects or projects that don't make money.

The alternative solution is to have an EC2 instance that runs MySQL instance which is going to be way cheaper but needs your maintenance. You'll need to do backups and other chores such scaling all the manual tasks.

Prerequisites

You need to either have secret .pem file to ssh to the EC2. Also make sure the port 3306 is enabled in your EC2 Security group rules. We assume your EC2 is running Ubuntu Linux.

Step 1: Install packages

Before we do anything I'm going to install tmux because it's great for running long-running process without canceling the process. For example, you are in the airport want to initiate some task that takes 15 minutes but the gate closes in 10 minutes so you need to start the process and close your terminal and move away. If you're not convinced, you can skip the following commands.

# update everytime before installing anything
sudo apt update

sudo apt install tmux # debian based linux

# start tmux
tmux

Install mysql-server package

sudo apt install mysql-server

Step 2: Register services

Add mysql to the background services so whenever the server restarts it will start too.

# start the service
sudo systemctl start mysql.service

Warning: you might get error Failed with result 'oom-kill' if that happens, you might need to upgrade to an EC2 instance with more RAM. I couldn't make it work on t4g.nano instance because it has less than 1GB RAM. To upgrade the EC2 instance, you'll need to stop it first by doing the following, (1) click in the top right Instance state dropdown > click Stop instance. (2) Click the next dropdown Actions > Instance Settings > Change instance type.

Step 3: Configure MySQL

When installation is complete, the mysql instance is not secure, so we need to make few changes to make it more secure.

# let's connect to it fisrt
sudo mysql

Set password for root user.

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your-password'
mysql> exit;

So, now we have set the password for the root user of our database, we need to run a built-in script for completing the steps to securing the database.

The mysql_secure_installation script takes you through steps by prompting you available security options.

sudo mysql_secure_installation

Make sure you choose your security options wisely.

Create User & Database

To access database it's good idea to use non-root user, which is why I prefer to use different user(s) for different databases/schemas. So, let's create a user db_user with a password (make sure you replace it with your password)

CREATE USER `db_user`@`%` IDENTIFIED WITH caching_sha2_password BY 'your-password';

CREATE DATABASE `db_name`;

GRANT ALL PRIVILEGES ON `db_name`.* TO `db_user`@`%`;

The % part in db_user@% means we can connect to this database from any machine that can connect to our EC2 instance.

Step 4: Connect from other EC2

You need to get your EC2 domain or IP to connect to the database.

mysql -h YOUR-EC2-IP -P 3306 -u db_user -p

Then you need to type your password after the prompt:

Enter password:

If you are using MySQL Workbench to access your databases, you can connect through SSH.

1. Click + icon near MySQL Connections

2. Click the Connection Method dropdown

3. Select the Standard TCP/IP over SSH option

4. Fill EC2 IP as the the SSH Hostname

5. Fill EC2 SSH username

6. Click the [...] button on the right of SSH Key File input, then Select .pem file we used to ssh to the EC2

7. The rest are Database Hostname, Username and password. These are the same as if you were connecting locally.

Conclusion

This solution is great for hosting your personal databases or projects that don't make money for you. If you make enough money from your project and the price is not too much for your revenue, I would suggest you use managed database server such as RDS or similar offerings from other cloud providers.

Introduction

Next.js is great serve-side oriented frontend framework that makes building SEO-friendly websites easier.

Deploying it is trickier than it needs to be, I understand Vercel needs to make money off of their creation. If you need an alternative way to deploy your website, dockerizing it will remove few of the headaches.

In this example, I'm using AWS EC2 for deployment but most of the steps would work on any other Linux VPS (Like Linode and etc)

Prerequisites

• AWS EC2 instance or any Linux server through SSH

• Basic understanding of:

  • Docker

  • Next.js

  • AWS EC2, make sure you have .pem file for authentication over SSH

  • Command-line interface

  • SSH client

Step 1: Prepare Your Next.js Application

Create Dockerfile for Next.js application with the following content:

FROM node:18-alpine AS base

# install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app

# install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
    if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
    elif [ -f package-lock.json ]; then npm ci; \
    elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
    else echo "Lockfile not found." && exit 1; \
    fi


# rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

RUN \
    if [ -f yarn.lock ]; then yarn run build; \
    elif [ -f package-lock.json ]; then npm run build; \
    elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
    else echo "Lockfile not found." && exit 1; \
    fi

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next
RUN chmod -R +x ./

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
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"]

Step 2: Configure and Install Docker

Let's connect to the EC2 instance using SSH.

# connect through ssh
ssh -i your-key-file.pem ec2-user2@ec2-YOUR-PUBLIC-IP.us-east-1.compute.amazonaws.com

Install tools

# update the packages before installing
sudo apt update

# install prerequisite packages
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# add the GPG key for the official Docker repo
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

# add repo to APT sources
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

# update packages again
sudo apt update

# reset apt cache to use the official repo instead of ubuntu sources
apt-cache policy docker-ce

# start the actual installation
sudo apt install -y docker-ce

# to verify the installation was successful, try
docker -v # prints the installed docker's version details

# check if the docker service is running
sudo systemctl status docker.service

# if not running, start it
sudo systemctl start docker.service

In case you hate prefixing every docker command with sudo you can do the following:

sudo usermod -aG docker $USER

# run this to refresh the current terminal session
su - $USER

Step 3: Deploy Docker Image to Docker hub or Github containers

To deploy the image of your dockerized project, you need to push it to a container repo like Docker Hub or Github containers. In this example, I'm using Github containers.

First we need to authenticate our local docker with our Github containers repo. We need an API token to use as password with docker login.

• Go to Gihtub.com Click on your profile picture on the top right.

• Click Settings

• Click Developer settings at the bottom of the left sidebar

• Click Personal access tokens to expand

• Click Tokens (classic)

• Click Generate new token dropdown

• Click Generate new token (classic) option

• Type the name of your project in the Node input

• Check write:packages and delete:packages checkboxes

• Finally click Generate token button near the bottom to complete this

sudo docker login ghcr.io # then give your github 
Username: your-github-username
Password: api-token-generated-above

Note: the generated API key is only shown once, so you need to keep it in a safe place to use it later to login to your Github container repository.

Let's create the images to deploy to our container repo we setup above.

# the --platform linux/amd64 is needed in case your machine is arm based, like Apple M-series or Snapdragon laptops.
docker build --platform linux/amd64 -t ghcr.io/your-github-username/project-name:v0.0.1 .

To use the image locally, let's stop if there any previous image running:

docker stop my-container-name # skip if it's the first time
docker rm my-container-name # skip the first time

# to run
docker run --rm --name my-container-name -d -p 3000:3000 ghcr.io/your-github-username/project-name:v0.0.1

After testing and making sure we have the container working as expected, let's push it to Github so we can pull from our EC2 server.

docker push ghcr.io/your-github-username/project-name:v0.0.1

Let's connect to the EC2 thourgh SSH again if not still connected:

# connect through ssh
ssh -i your-key-file.pem ec2-user2@ec2-YOUR-PUBLIC-IP.us-east-1.compute.amazonaws.com

Let's pull the docker image from github. NOTE: you need to login using the above docker login step and use the same username and API-token as the password.

sudo docker pull ghcr.io/your-github-username/project-name:v0.0.1

Then let's run a container from the docker image we downloaded.

sudo docker run --rm --name my-container-name -d -p 3000:3000 ghcr.io/your-github-username/project-name:v0.0.1

Step 4: Implement Production Optimizations

Setup NGINX

If you don't already have nginx installed, let’s quickly do that

sudo apt update
sudo apt install -y nginx

Let's create a config file for our site for nginx to the HTTP handle requests

sudo touch /etc/nginx/sites-available/my-site-domain.com
sudo nano /etc/nginx/sites-available/my-site-domain.com

Then copy the following content in the file you just opened.

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name _  www.my-site-domain.com.com my-site-domain.com.com;
    error_log /var/log/nginx/error.log warn;
    access_log /var/log/nginx/access.log;

    # root /var/www/html;
    root /var/www/html;

    location / {
          proxy_pass      http://127.0.0.1:3000;
          proxy_set_header Host $http_host;
          proxy_redirect off;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          # try_files $uri $uri/ =404;
    }
}

We need to link the config file to a file in sites-enabled folder. Creating a link file helps you keep the config file and be able to enable/disable that config by creating or removing the link file, while keeping the actual config file in sites-available.

sudo ln -s /etc/nginx/sites-available/my-site-domain.com /etc/nginx/sites-enabled/my-site-domain.com

Generate SSL Certificates with Certbot

There are other ways to setup SSL on AWS but I like a portable solution that can be used on any Linux VPS. So, we're going to use Let's Encrypt Certbot tool to generate SSL certificates.

# install certbot
sudo snap install --classic certbot

# create a link for the certbot binary
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# let's run the certbot command
sudo certbot --nginx

Common Troubleshooting

The issue I always find is when forget to prefix sudo in docker commands, so if you didn't add docker user to the sudo group, you might get an issue like

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock:

The error doesn't give a suggestion to why this is happening so you might need to run the command again with sudo or follow last part of installing docker above.

Conclusion

Deploying Next.js apps isn't hard as we showed above but there are no clear guides available. This was the only way that worked for me and I thought I have to share with the community as it might save you sometime. If you have any suggestions of how we can improve the above guide, please feel free to share them.

Additional Resources

• Docker documentation

• Next.js deployment guides

• AWS EC2 documentation

• Certbot Ubuntu Nginx Guide

Why do you need a single Executable?

Why don't you share the whole dist folder as a zip so it can be hosted by the client? sharing the actual files increases exposure of your code to be reverse engineered. It will also be easier for people to change the code, for example, to avoid paying your subscription. An experienced hacker will still find a way but this will create a new layer of security because your javascript files are not visible in the host machine.

I'm using React as an example for this demo but you can use your favorite frontend stack by making the necessary go code changes. If you are interested on seeing your favorite stack deployed this way, please leave a comment below.

Let's setup a demo React app

Please skip to the next section if you already have your react app set up. In this example, we are using vite to create the react app.

npm create vite@latest react-example-app -- --template react

Let's go in the newly created react project and complete the setup.

cd react-example-app
npm install # install dependencies
npm run dev # run the app locally

Let's go on the default URL on http://localhost:5173 to see if our react app is running.

Now we have the app running, let's setup a go package, this is only a single file go project so you can create it within your frontend project.

Let's create a serve.go file at the root of our project, then add the following content:

// serve.go
package main

import (
    "embed"
    "html/template"
    "io/fs"
    "log"
    "net/http"
    "os"

    "github.com/gin-gonic/gin"
)

// this contains special comments that instruct the go compiler to embed the files within the executable.
var (
    //go:embed dist/*
    dist embed.FS

    //go:embed dist/index.html
    indexHTML string

    //go:embed dist/assets/*
    assets embed.FS

    IndexTemplate *template.Template
)

// this is called before any other code in this file runs
func init() {
    // setup HTML renderer with the embedded index.html
    IndexTemplate = template.New("index.html")
    var err error
    IndexTemplate, err = IndexTemplate.Parse(indexHTML)
    if err != nil {
        panic(err)
    }
}

func main() {
    // create gin router
    router := gin.Default()
    // set the embedded index.html as the go template
    router.SetHTMLTemplate(IndexTemplate)

    // this gives you the option the change the port after the executable is created
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    // static files in dist/assets
    assetsFs, err := fs.Sub(assets, "dist/assets")
    if err != nil {
        panic(err)
    }

    // serve the contents of assets folder in /assets URL path
    router.StaticFS("/assets", http.FS(assetsFs))

    // handle all routes
    router.NoRoute(func(c *gin.Context) {
        // NOTE: if you're running an API alongside your frontend, you'll want to do the following to skip the /api endppoints
        if len(c.Request.URL.Path) >= 4 && c.Request.URL.Path[:4] == "/api" {
            c.Next()
            return
        }

        c.HTML(http.StatusOK, "index.html", gin.H{})
    })

    log.Printf("Server is running on port %s", port)
    if err := router.Run(":" + port); err != nil {
        log.Fatalf("Server failed to start: %v", err)
    }
}

Before we can run the go code, we need to initialize the go package. We named it web-go-server but you can call it anything you want.

go mod init web-go-server # sets up the required files for t
go mod tidy # to initialize imported packages in go.sum, this is like the package.json for go projects.

Let's test what we have so far.

# make sure you build the fontend, or there will be no dist folder to embed in the executable.
# you'll get this error if you skip this step:
# serve.go:15:13: pattern dist/*: no matching files found
npm run build

# then run the go code
go run .

Now we have our frontend served through our go code, the static files are going to be embedded within the executable file so we'll leave the dist folder behind and don't need to share alongside the executable.

As you can see in the screenshot below, we are missing the vite.svg file this is from the public folder, we can't serve the contents of the whole dist folder as the root because that would conflict with the index.html we serve from the root path / to work around this we need to move the public/vite.svg to src/assets/vite.svg you do the same for any other static file you have in the public folder. In case you don't want to move any file to the assets place them in public/static so we can modify the go code to serve that as well.

// static files in dist/static
staticFs, err := fs.Sub(dist, "dist/static")
if err != nil {
    panic(err)
}

router.StaticFS("/static", http.FS(staticFs))

Then edit anywhere the static file is referred to in your frontend code and make sure all images are showing (Screenshot below).

What do we have?

This is how the whole project is structured:

.
├── README.md
├── eslint.config.js
├── go.mod
├── go.sum
├── index.html
├── package.json
├── pnpm-lock.yaml
├── public
│   └── vite.svg
├── src
│   ├── App.css
│   ├── App.jsx
│   ├── assets
│   │   └── react.svg
│   ├── index.css
│   └── main.jsx
├── vite.config.js
└── serve.go

Let's create the executable binary file

After you have everything setup and everything is working when you run go run . you need to create the executable you share with your clients.

# run the fontend build again to make sure no changes left out
npm run build

# build the go executable
go build -o your-app-name .

To build for multiple platforms:

The above command creates an executable that runs on your current machine and any machine that is using the same CPU architecture but Golang allows you to cross-compile to all supported CPUs using your current machine.

# for windows
GOOS=windows GOARCH=amd64 go build -o your-app-name.exe .

# for linux x86
GOOS=linux GOARCH=amd64 go build -o your-app-name .

# for linux arm64 like rasbperry pi
GOOS=linux GOARCH=arm64 go build -o your-app-name .

# for macos intel x86 64
GOOS=darwin GOARCH=amd64 go build -o your-app-name .

# for macos Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o your-app-name .

I hope this helped you ship your SaaS fast using this method, if you like this kind of content please feel free to follow me and subscribe to my newsletter.

I don't think it's feasible to buy a license to test few things in a virtual machine.

If you are in the same situation as me and hate light mode because it hurts your eyes, here is a single command to change the system theme to dark.

Step 1: Open Windows Powershell

Click the start button or press Window key, then type powershell and click Window Powershell

Step 2: Copy Command to Powershell

Paste the command below in the Powershell Window and press Enter to run the command.

rundll32.exe themecpl.dll,OpenThemeAction C:\Windows\resources\themes\dark.theme

Changed your mind?

If you don't want this theme and need to use a different one, check the available themes using this command:

dir C:\Windows\resources\themes\*.theme

Then replace the last part of the previous command dark.theme with whatever theme you want. For example, you want to use themeC.theme instead:

rundll32.exe themecpl.dll,OpenThemeAction C:\Windows\resources\themes\themeA.theme

NOTE: You might need to restart and rerun the command for changes to take effect.

Sometimes, building your own authentication REST API sounds scary but in this post, I'll show you how it's done using Node.js and Express.js. In this post you'll see how to build your own email/password authentication system.

Setting up your Node.js project

Let's initialize the express.js project

mkdir example-auth-api
cd example-auth-api
npm init -y
npm install express bcrypt jsonwebtoken body-parser

Setting up Express.js endpoints

Let's import all the required libraries

const express = require('express');
const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');
const bodyParser = require('body-parser');

Then let's instantiate our express app.

const app = express();
app.use(bodyParser.json());

Let's add signUp, login as public routes and userProfile protected endpoint.

app.post('/signup', signUp);
app.post('/login',login);
app.get('/users', authMiddleware, userProfile);

Now, let's create the signUp endpoint handler.

const signUp = async (req, res) => {
    try {
        const { email, password } = req.body;

        // check if a user with the current email exists
        try {
            await getUserByEmail(email);
            return res.status(400).json({ error: 'User with this email already exists' });
        } catch (err) {
            // this means we can continue with signup
        }

        // hash the password
        const hashedPassword = await bcrypt.hash(password, HASH_COST);

        // save the user
        const user = new User(Date.now(), email, hashedPassword);
        await CreateUserInDb(user);

        res.status(201).json({
            message: 'User created successfully',
            email: user.email
        });
    } catch (err) {
        res.status(400).json({ error: 'Failed to create user' });
    }
}

Now, let's create login endpoint handler.

const login = async (req, res) => {
    try {
        const { email, password } = req.body;

        // Get user by email
        let user;
        try {
            user = await getUserByEmail(email);
        } catch (err) {
            return res.status(401).json({ error: 'Invalid email or password' });
        }

        // Verify password
        const isValid = await bcrypt.compare(password, user.password);
        if (!isValid) {
            return res.status(401).json({ error: 'Invalid email or password' });
        }

        // Generate tokens
        const { token, refreshToken } = generateToken(user);

        res.status(200).json({
            message: 'Login successful',
            token,
            refreshToken
        });
    } catch (err) {
        res.status(401).json({ error: 'Invalid email or password' });
    }
}

This endpoint verifies the user's credentials and generates a token. In production, use a library to create a secure JWT token and hashing passwords.

And finally, the userProfile endpoint handler.

const userProfile = async (req, res) => {
    try {
        const userId = req.userId;
        const user = await GetUserByID(userId);
        res.json({ user });
    } catch (err) {
        res.status(401).json({ error: 'Access Denied!' });
    }
}

Protecting Private Routes

In order to protect our private routes we need to use a middleware that keeps non-authenticated HTTP calls to our protected rourtes. As an example, we have 1 protected route that returns the current user's details. Note: it's not recommended to return the full details of the user, this might include sensitive data such as password hash or other unintended leaks.

const authMiddleware = async (req, res, next) => {
    const authHeader = req.headers.authorization;
    if (!authHeader) {
        return res.status(401).json({ error: 'Authorization header missing' });
    }

    const tokenString = authHeader.replace('Bearer ', '');
    try {
        const token = jwt.verify(tokenString, JWT_SECRET);

        if (!token.sub || token.typ !== 'authentication') {
            return res.status(401).json({ error: 'Invalid token claims' });
        }

        req.userId = token.sub;
        next();
    } catch (err) {
        return res.status(401).json({ error: 'Invalid token' });
    }
};

Complete example

Here is the complete example code:

// User model
class User {
    constructor(id, email, password) {
        this.id = id;
        this.email = email;
        this.password = password;
    }
}

const express = require('express');
const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

// Constants, please use .env to securely store instead of hardcoding it here.
const JWT_SECRET = 'your-secret-key';
const JWT_AUD_NAME = 'your-audience';
const JWT_ISSUER_NAME = 'your-issuer';
const TOKEN_EXPIRATION_DURATION = '1h';
const REFRESH_TOKEN_EXPIRATION_DURATION = '7d';
const HASH_COST = 10;

// TODO: create your implementation of the database access function
async function getUserByEmail(email) {
    throw new Error('User not found');
}

async function getUserByID(id) {
    throw new Error('User not found');
}

async function CreateUserInDb(user) {
    return true;
}

// Middleware
const authMiddleware = async (req, res, next) => {
    const authHeader = req.headers.authorization;
    if (!authHeader) {
        return res.status(401).json({ error: 'Authorization header missing' });
    }

    const tokenString = authHeader.replace('Bearer ', '');
    try {
        const token = jwt.verify(tokenString, JWT_SECRET);

        if (!token.sub || token.typ !== 'authentication') {
            return res.status(401).json({ error: 'Invalid token claims' });
        }

        req.userId = token.sub;
        next();
    } catch (err) {
        return res.status(401).json({ error: 'Invalid token' });
    }
};

// Generate JWT tokens
function generateToken(user) {
    const now = Math.floor(Date.now() / 1000);
    const claims = {
        sub: user.id,
        typ: 'authentication',
        aud: JWT_AUD_NAME,
        exp: now + (60 * 60), // 1 hour
        nbf: now,
        iat: now,
        iss: JWT_ISSUER_NAME
    };

    const token = jwt.sign(claims, JWT_SECRET);

    claims.typ = 'refresh';
    claims.exp = now + (7 * 24 * 60 * 60); // 7 days
    const refreshToken = jwt.sign(claims, JWT_SECRET);

    return { token, refreshToken };
}

// Routes
app.post('/signup', signUp);
app.post('/login',login);
app.get('/profile', authMiddleware, userProfile);

const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

Conclusion

This simple example shows how to build an email/password authentication REST API. You can expand this by integrating database and implementing getUserByEmail and getUserByID functions. With these building blocks, you're well on your way to create a fully functional authentication system.

Warning: Whatever you do, never try to build your own hashing function. You can also secure your API by using multiple layers of protection, such as OS-level firewall that only allows access to ports you want access from outside.

Please comment below if you're interested in expanding this to also add social authentication providers such as Google or Facebook, etc.

Setting Up the Gin Router

Let's initialize the go project first

go mod init example-auth-api
go mod tidy

To start, we need to set up a basic Gin router with endpoints for user sign-up and login.

// main.go
package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func main() {
    router := gin.Default()

    router.POST("/signup", SignUpUser)
    router.POST("/login", LoginUser)

    userGroup := router.Group("/users")
    userGroup.Use(AuthMiddleware())
    {
        userGroup.GET("/", UserProfile)
    }

    router.Run(":8080")
}

This code creates a simple web server that listens for incoming requests. Now let’s implement the sign-up and login logic.

Sign-Up Endpoint

Here’s the function to handle user sign-ups:

// handlers.go

func SignUpUser(c *gin.Context) {
    var user User

    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid input"})
        return
    }

    // check if a user with the current email exists
    existingUser, err := GetUserByEmail(user.Email)
    exists := err == nil || (err != nil && IsNotFoundError(err))
    if exists {
        c.JSON(http.StatusBadRequest, gin.H{"error": "User with this email already exists"})
        return
    }

    // hash the password
    bytes, err := bcrypt.GenerateFromPassword([]byte(password), HASH_COST)
    if  err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Failed to hash password"})
        return
    }

    user.Password = string(bytes)

    // save the user
    if err = CreateUserInDb(user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Failed to create user"})
        return
    }

    c.JSON(http.StatusCreated, gin.H{
        "message": "User created successfully",
        "email": user.Email,
        "password": hashedPassword,
    })
}

This function processes incoming JSON data, hashes the password, and returns a success message. Always remember to hash passwords securely in a real application.

Login Endpoint

Next, we implement the login functionality:

// handlers.go

func LoginUser(c *gin.Context) {
    var user User

    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid input"})
        return
    }

    // Get user by email
    user, err := GetUserByEmail(user.Email)
    if err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid email or password"})
        return
    }

    if success := user.Authenticate(); success {
        if token, refresh, err := generateToken(user); err != nil {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid email or password"})
        } else {
            c.JSON(http.StatusOK, gin.H{
                "message": "Login successful",
                "token": token,
                "refreshToken": refresh,
            })
        }
    } else {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid email or password"})
    }
}

This endpoint verifies the user’s credentials and generates a token. In a production app, use a library to create secure JWT tokens.

Protecting Private Routes

In order to protect our private routes we need to use a middleware that keeps non-authenticated HTTP calls to protected routes. As an example, we have 1 protected route that returns the current user's details. Note: it's not recommended to return the full details in a user, this might include sensitive data such as password hash.

func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        authHeader := c.GetHeader("Authorization")
        if authHeader == "" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Authorization header missing"})
            c.Abort()
            return
        }

        tokenString := strings.TrimPrefix(authHeader, "Bearer ")
        token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
            return []byte(JWT_SECRET), nil
        })

        if err != nil || !token.Valid {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"})
            c.Abort()
            return
        }

        claims, ok := token.Claims.(jwt.MapClaims)
        // check if claims are not a valid jwt.MapClaims, the user id is missing or the token is not for authentication.
        if !ok || claims["sub"] == nil || claims["typ"] != "authentication" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token claims"})
            c.Abort()
            return
        }

        c.Set("user_id", claims["sub"])
        c.Next()
    }
}

Complete Example

Here’s the complete code for this simple API:

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

type User struct {
    ID       uint64   `json:"id"`
    Email    string `json:"email"`
    Password string `json:"password"`
}

func main() {
    router := gin.Default()

    router.POST("/signup", SignUpUser)
    router.POST("/login", LoginUser)

    userGroup := router.Group("/users")
    userGroup.Use(AuthMiddleware())
    {
        userGroup.GET("/", UserProfile)
    }

    router.Run(":8080")
}

func SignUpUser(c *gin.Context) {
    var user User

    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid input"})
        return
    }

    // check if a user with the current email exists
    existingUser, err := GetUserByEmail(user.Email)
    exists := err == nil || (err != nil && IsNotFoundError(err))
    if exists {
        c.JSON(http.StatusBadRequest, gin.H{"error": "User with this email already exists"})
        return
    }

    // hash the password
    bytes, err := bcrypt.GenerateFromPassword([]byte(password), HASH_COST)
    if  err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Failed to hash password"})
        return
    }

    user.Password = string(bytes)

    // save the user
    if err = CreateUserInDb(user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Failed to create user"})
        return
    }

    c.JSON(http.StatusCreated, gin.H{
        "message": "User created successfully",
        "email": user.Email,
        "password": hashedPassword,
    })
}

func LoginUser(c *gin.Context) {
    var user User

    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid input"})
        return
    }

    // Get user by email
    user, err := GetUserByEmail(user.Email)
    if err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid email or password"})
        return
    }

    if success := user.Authenticate(); success {
        if token, refresh, err := generateToken(user); err != nil {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid email or password"})
        } else {
            c.JSON(http.StatusOK, gin.H{
                "message": "Login successful",
                "token": token,
                "refreshToken": refresh,
            })
        }
    } else {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid email or password"})
    }
}

func UserProfile(c *gin.Context) {
    // example of getting the user_id from the request context.
    id, ok := c.MustGet("user_id").(uint64)
    if !ok || id < 1 {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Access Denied!"})
        return
    }

    user, err := GetUserByID(id)
    if err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Access Denied!"})
        return
    }

    c.JSON(http.StatusOK, gin.H{"user": user})
}

func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        authHeader := c.GetHeader("Authorization")
        if authHeader == "" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Authorization header missing"})
            c.Abort()
            return
        }

        tokenString := strings.TrimPrefix(authHeader, "Bearer ")
        token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
            return []byte(JWT_SECRET), nil
        })

        if err != nil || !token.Valid {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"})
            c.Abort()
            return
        }

        claims, ok := token.Claims.(jwt.MapClaims)
        // check if claims are not a valid jwt.MapClaims, the user id is missing or the token is not for authentication.
        if !ok || claims["sub"] == nil || claims["typ"] != "authentication" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token claims"})
            c.Abort()
            return
        }

        c.Set("user_id", claims["sub"])
        c.Next()
    }
}

func generateToken(u User) (tokenStr string, refreshStr string, err error) {
    now := time.Now()
    claims := jwt.MapClaims{
        "sub":  u.ID,
        "typ": "authentication",
        "aud":  JWT_AUD_NAME,
        "exp":  now.Add(TOKEN_EXPIRATION_DURATION).Unix(),
        "nbf":  now.Unix(),
        "iat":  now.Unix(),
        "iss":  JWT_ISSUER_NAME,
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS512, claims)
    tokenStr, err = token.SignedString([]byte(JWT_SECRET))
    if err != nil {
        return "", "", err
    }

    claims["typ"] = "refresh"
    claims["exp"] = now.Add(REFRESH_TOKEN_EXPIRATION_DURATION).Unix()

    refresh := jwt.NewWithClaims(jwt.SigningMethodHS512, claims)
    refreshStr, err = token.SignedString([]byte(JWT_SECRET))
    if err != nil {
        return "", "", err
    }

    return refreshStr, tokenStr, nil
}

Conclusion

This simple example shows how to build an email/password authentication REST API. You can expand this by integrating a secure database and implement the GetUserByID and GetUserByEmail functions. With these building blocks, you're well on your way to creating a full-featured authentication system.

Warning: Whatever you do, never try to build your own hashing function. You can also secure your API by using multiple layers of security, such as an OS-level firewall that only allows ports you want accessed from outside. Also, you need to set up trusted proxies using gin's built-in function router.SetTrustedProxies; this will reject requests that are coming from URLs that are not yours. Someone can still bypass this spoofed headers, but still, it helps you protect from script kiddies.

Please comment below if you are interested in expanding this to also add social authentication providers such as Google or Facebook, etc.