DEV Community: shun

On self hosting outline wiki

shun — Tue, 14 Jul 2026 07:36:35 +0000

read the original blog here: https://astonepokes.net/reflections/on-self-hosting/

Before we start

this article serves as a reflection and reminder to myself on what occurred when i tried to self host outline wiki

Context

I've an old laptop lying around with these specs:

Memory: 32 gb
Storage: 1tb sdd
Cpu: i7-1165G7 (4 cores / 8 threads)
Graphics: Intel Iris Xe integrated graphics

and I thought: "I could turn this into a homelab for me to tinker and learn self hosting so why not?". originally, I wanted to run local LLMs like gemma 4 on this hardware but I realised the graphics card wasn't up for it.

thus, i formatted the laptop to use ubuntu 26.04, which seemed to be the most beginner friendly way to start.

What I decided on

i took some time to figure out what I want on the server, and settled on self hosting both caddy and outline.

I've used outline wiki before and I liked it a lot. It was fast, less clunky than confluence and it can be self hosted with docker.

also, I wanted to learn how to setup a reverse proxy with caddy. out of the box, it provides self signed certificates for SSL which is quite convenient as well because I only want to access everything within my local area network (LAN).

i thought the process will be quite straightforward, it'd be a one day job and I'd have scratched my itch to learn.

install caddy on bare metal, setup reverse proxy
setup docker
get outline wiki docker compose, setup environment variables and start the docker compose
voila, i'd have my outline wiki ready to access across my lan

However, self hosting outline wiki required more work than I expected.

The trip up

i assumed outline supported email and password authentication, but they didn't. instead, it offers third party authentication such as Google, Gitlab, Discord and so on but I didn't like the idea of relying on an online service for authentication so I needed to configure oidc.

since I decided to use caddy, I couldn't use the recommended https-portal which provides a lets encrypt cert out of the box. I had to figure out how to use caddy to issue self signed certificate on the reverse proxied route on outline wiki.

lastly, I didn't want to pay a dime for a domain which made it that much more harder for myself.

What I did

after experimenting, I settled on the following architecture

Technitium - A DNS server to create a DNS zone called marseille.internal and hostnames like outline.marseille.internal and authelia.marseille.internal
- .internal or .home.apra are reserved keywords from ICANN for private use
Caddy - A reverse proxy to expose outline wiki with a proper hostname like outline.marseille.internal instead of remembering the ip and port (192.168.1.141:3100)
Authelia - A OIDC provider which supports email and password authentication for outline wiki
Outline wiki - the application I want to self host

Rationale

Technitium, authelia and caddy are installed on bare metal. These applications are going to be used by one or more services, and there isn't a need for scaling, so I skipped docker and the need to deal with an additional layer of networking.

Outline wiki is on a docker container. It's an application I could switch out any time if I wanted to, and I didn't want any lingering dependencies if I ever removed it. It has its own internal network, saving me the trouble of dealing with port conflicts with commonly used service like redis or postgres.

Reminders

These are reminders to myself on what I did to both technitium and authelia.

Technitium

Setting up technitium was straightforward, I followed the instructions here.

Fortunately, I didn't run into any issues with port binding as mentioned in: Common Issue With Ubuntu. Once everything was done, I checked the status with sudo systemctl status.service and visited http://localhost:5380

Once in, I created the following A records for authelia and outline.

authelia.marseille.internal -> 192.168.1.141:9091
outline.marseille.internal -> 192.168.1.141:3100

Authelia

Setting up authelia was quite unintuitive, the docs didn't give much instructions on how to start post installation. After following the installation guide. I expected some docs along the lines of "here are the commands to get you started" or "here's a guide to ubuntu" but there was none. Only Get Started existed.

Thankfully, I remembered authelia runs with systemd on bare metal. So I figured that if I ran sudo systemctl status authelia.service something would pop up and it did!

updating configuration

It showed me a bunch of errors regarding an incomplete configuration.yml, showed me where the file (/etc/authelia/configuration.yml) was and what to fix. In this case its something about the telemetry key, heading to the docs I can find more information about telemetry and configure it.

After addressing the issue and saving the configuration file, I just needed to run sudo systemctl restart authelia and sudo systemctl status authelia --full --no-pager to ensure that everything works

Seeding initial users

authelia requires a default user to be created, which is defined within the /etc/authelia/configuration.yml.

I populated it like so following the setup mentioned

With the user seeded, I visited the https://authelia.marseille.internal and logged in

Outline works!

With authelia in place, and adding its oidc creds to authelia based on https://www.authelia.com/integration/openid-connect/clients/outline/ .
I could visit https://outline.marseille.internal

Takeaways

I never expected self hosting outline wiki to be such a journey, it took five days instead of one! Along the way, it refreshed my memory on so many things such as

what does my router do again?
what does a dns server do? and how does technitium help in this case
reading the docs and figuring out how to setup tools like authelia
get it through my head that reverse proxy is literally a collection of internal ip address and port to a public domain or subdomain

and so on.

All these to scratch my itch of self hosting. With this new found knowledge, I realise self hosting isn't as difficult as I thought. Though certain application like outline wiki can give a big trip, but I feel like with the current architecture I have can go a long way.

So what's my biggest lesson here? I'd say it's remembering the process matters more than the outcome. I know I'll be able to self host outline wiki (outcome) but I tend to procrastinate thinking that it'll be easy, and as it turns out it wasn't and I learned a lot.

So if I procastinate it means I should probably do it, sounds like a pretty good signal to do stuff.

Thoughts on Write yourself a Git!

shun — Fri, 28 Feb 2025 04:21:59 +0000

Article in question: https://wyag.thb.lt/

Going through this article provided me with a deeper understanding on how Git works. It's a tool which we use daily but don't really understand how it works.

I ask myself was there any point of this? I'm not sure really, I won't be asked to build my own Git. But, it was interesting to understand or have an inkling on how Git works at its core. Moreover, there were moments where I find myself saying: 'Oh this is how it works' and feel a tinge of excitement which I've not felt in a while.

It was cool to consume, verify and implement the content of the article. For example, it mentions that Git objects exists in .git/objects, I proceeded to verify it and confirm that it actually exists. Additionally, now I understand how the folders and file are structured under it. The first two character of the SHA-1 hash is the folder name and the remaining characters is the binary file name.

Though I mentally checked out on part 9, I pressed on and went through the article in one pass. There are still a lot of concepts that are still unknown / abstract / confusing to me such as a tree object. In the article it mentions that a tree object is special as it's a binary object but aren't tags and commit binary objects too?

But I tend to not dwell too much on it, I just note it down, move forward and complete the tutorial to get a bigger picture allowing me to connect the dots backwards.

Other than noting down parts I'm not sure on, I wrote down a question and answer deck along the way so that I can insert into Anki for revision. For example:

What is a git object? Git objects are binary file that represent files within a repository. These objects usually lives in '.git/object' and it's identified by a SHA-1 hash which is derived from the contents of the file. Thus git doesn't actually store files
What happens when a file in git is modified? Instead of updating a file, a new file is created in a different location

Lastly, I'm going through this content a second ~ nth time to reinforce the concept taught, modifying the code to reflect my understanding and reduce cognitive load. For example, I'm intending to split up the different git commands to separate files for easy reading and introduce typings to the parameters to know what it should expect. But this is only possible if I've went through it the first time round. Essentially, I'm replicating first before iterating the content with my own twist

For those interested in the code I've written up it's here: https://github.com/tanshunyuan/build-my-own-x/tree/main/wyagit

Preventing account sharing with Clerk

shun — Mon, 03 Jun 2024 14:40:28 +0000

Scenario

Imagine the following scenario:

When User B logs in using User A's credentials from a different device, the platform invalidates User A's active session, logs them out, and allows User B to access the account to prevent account sharing.

The Problem

While Clerk provides a way to invalidate a user session, there aren't any docs or guides on achieving the said scenario. Thus, I've written this guide to illustrate the process.

The Guide

Before we continue

Disclaimer

This walkthrough will not cover how Clerk was set up with TRPC & NextJS 14 as seen in the example repo. It'll only go through the core logic/implementation of preventing account sharing.

Tech Stack

This guide uses the following tech stack:

Create T3 APP
- NextJS 14 app directory
- TRPC 11
Pusher Channels
- We'll be using the free tier which allows for 200k messages per day & 100 concurrent connection.
Clerk

While it's using bleeding edge tech, I believe the concept described in the guide can be used on a traditional client-server architecture as well.

Folder Structure

src
├── app
│   ├── (auth)
│   │   ├── layout.tsx
│   │   └── sign-in
│   │       └── [[...sign-in]]
│   │           └── page.tsx
│   ├── (internal)
│   │   └── app
│   │       ├── dashboard
│   │       │   └── page.tsx
│   │       └── layout.tsx
│   ├── api
│   │   └── pusher
│   │      └── auth
│   │          └── route.ts
│   └── layout.tsx
├── hooks
│   └── use-setup-session-management.ts
├── lib
│   └── pusher
│       ├── client.ts
│       └── server.ts
├── server
│   └── api
│       └── routers
│          └── user.ts
└── utils
    ├── app-provider.tsx
    └── route-paths.ts

Implementation

The full code is right here

Configuring a web socket service on your application

With a pusher account, follow it's JS SDK walkthroughto retrieve the environment variables from your account.

Now we need to setup a client and server pusher instance as follows:

Client

// src/lib/pusher/client.ts

import PusherClient from "pusher-js";
import { env } from "~/env.js";

const PUSHER_AUTH_ENDPOINT = "/api/pusher/auth";
export const pusherClient = new PusherClient(env.NEXT_PUBLIC_PUSHER_KEY, {
  cluster: env.NEXT_PUBLIC_PUSHER_CLUSTER,
  authEndpoint: PUSHER_AUTH_ENDPOINT,
});

Notes

PUSHER_AUTH_ENDPOINT is an authentication endpoint that will be called on the client side to authenticate the outgoing request to the server.

Server

// src/lib/pusher/server.ts

import PusherServer from "pusher";
import { env } from "~/env.js";

let pusherInstance: PusherServer | null = null;

export const getPusherInstance = () => {
  if (!pusherInstance) {
    pusherInstance = new PusherServer({
      appId: env.PUSHER_APP_ID,
      key: env.NEXT_PUBLIC_PUSHER_KEY,
      secret: env.PUSHER_SECRET,
      cluster: env.NEXT_PUBLIC_PUSHER_CLUSTER,
      useTLS: true,
    });
  }
  return pusherInstance;
};

Authenticating Client Pusher Request on the server

// src/app/api/pusher/auth/route.ts

import { getPusherInstance } from "~/lib/pusher/server";

const pusherServer = getPusherInstance();

export async function POST(req: Request) {
  // see https://pusher.com/docs/channels/server_api/authenticating-users
  const data = await req.text();
  const [socket_id, channel_name] = data
    .split("&")
    .map((str) => str.split("=")[1]);

  // use JWTs here to authenticate users before continuing
  try {
    const auth = pusherServer.authorizeChannel(socket_id!, channel_name!);
    return new Response(JSON.stringify(auth));
  } catch (error) {
    console.error("pusher/auth.handler.catch", { details: error });
  }
}

Establish a client web socket connection

Client: Creating a hook

// src/hooks/use-setup-session-management.ts

import { useUser } from "@clerk/nextjs";
import { pusherClient } from "~/lib/pusher/client";
import { useState } from "react";

let didInit = false;
export const useSubscribeToSessionChannel = () => {
  const { user } = useUser();

  useEffect(() => {
    if (!didInit) {
      const channel = pusherClient
        .subscribe("private-session")
        .bind(
          `evt::revoke-${user?.id}`,
          (data: { type: string; data: string[] }) => {
            if (data.type === "session-revoked") {
                // handle session removal
            }
          },
        );
      didInit = true;

      return () => {
        channel.unbind();
        didInit = false;
      };
    }
  }, [user, handleSessionRemoval]);
};

Notes:

didInit
- Ensures that the hook only run once when mounted. More here
pusherClient.subscribe('private-session')
- private-session is the channel name
pusherClient.subscribe('private-session').bind('evt::revoke-${user?.id})
- evt::revoke-${user?.id} is the event name to be triggered within the channel.

Client: Mounting it in the protected directory provider

// src/utils/app-provider.tsx

'use client'
import { useSubscribeToSessionChannel } from "~/hooks/use-setup-session-management";
import { type BaseChildrenProps } from "~/types/common";

export const AppProvider = (props: BaseChildrenProps) => {
  const { children } = props

  useSubscribeToSessionChannel();

  return <>
    {children}
  </>
}

Notes:

By putting it in a provider it means that every time the user visits the main application. This connection will be setup ## Query for extra session on the server side

Server

// src/server/api/routers/user.ts

import { clerkClient } from "@clerk/nextjs/server";
import { createTRPCRouter, protectedProcedure } from "../trpc";
import { getPusherInstance } from '~/lib/pusher/server';

const pusherServer = getPusherInstance();

export const userRouter = createTRPCRouter({
  getExcessSessions: protectedProcedure.query(async ({ ctx }) => {
    const { userId, sessionId: currentSessionId } = ctx.auth;

    const { data: activeSessions } = await clerkClient.sessions.getSessionList({
      userId,
      status: "active",
    });

    if (activeSessions.length <= 1) return null;

    const excessSessionsIds = activeSessions
      .filter((session) => session.id !== currentSessionId)
      .map((session) => session.id);

    const revokeSessionsPromises = excessSessionsIds.map((sessionId) =>
      clerkClient.sessions.revokeSession(sessionId),
    );

    try {
      await Promise.all(revokeSessionsPromises).then(async () => {
        await pusherServer
          .trigger("private-session", `evt::revoke-${userId}`, {
            type: "session-revoked",
            data: excessSessionsIds,
          })
      });
    } catch (error) {
      console.error(error);
    } finally {
      return {};
    }
  }),
})

Notes

Ensure both channelName & eventName for pusher is the same as the one on the client side

Client

// src/utils/app-provider.tsx 

'use client'
import { useSubscribeToSessionChannel } from "~/hooks/use-setup-session-management";
import { api } from "~/trpc/react";
import { type BaseChildrenProps } from "~/types/common";

export const AppProvider = (props: BaseChildrenProps) => {
  const { children } = props

  useSubscribeToSessionChannel();
  const excessSessionQuery = api.user.getExcessSessions.useQuery()

  if (excessSessionQuery.isLoading) return <p>Loading...</p>

  return <>
    {children}
  </>
}

Sign user out based on extra sessions

We're going to handle the information from the callback in the web socket connection

We'd need to define how to handle the session removal when the web socket receives an item:

// src/hooks/use-setup-session-management.ts

const useHandleSignOut = () => {
  const { signOut } = useClerk();
  const router = useRouter();

  return async (currentSessionId: string) => {
    await signOut(() => {
      router.push(`${ROUTE_PATHS.SIGNIN}?forcedRedirect=true`);
    }, {
      sessionId: currentSessionId
    })
  }
};

const useHandleSessionRemoval = () => {
  const { session: currentSession } = useClerk();
  const handleSignOut = useHandleSignOut();

  return async (excessSessionIds: string[]) => {
    try {
      const hasExcess = excessSessionIds.length > 0;
      const isCurrentSessionExcess =
        hasExcess && currentSession && excessSessionIds.includes(currentSession.id);

      if (!isCurrentSessionExcess) return;

      await handleSignOut(currentSession.id);
    } catch (error) {
      console.error('Error removing session:', error);
    }
  };
};

Using use as a keyword to prevent typescript from complaining

Refer to here for the full code.

Touching up the UI

After the user is signed out, they'll be redirected to the sign in page. At this point we'd want to notify the user that they've been logged out.

Recall this is how we redirected the user

router.push(`${ROUTE_PATHS.SIGNIN}?forcedRedirect=true`);

Notice the query parameter of forcedRedirect=true, this is used to trigger a toast to indicate the user they've been logged out on the sign in page.

Here's how:

// src/app/(auth)/sign-in/[[...sign-in]]/page.tsx

"use client";
import { SignIn } from "@clerk/nextjs";
import { useSearchParams, useRouter } from "next/navigation";
import { useEffect } from "react";
import { ROUTE_PATHS } from "~/utils/route-paths";
import toast from "react-hot-toast";

export default function SignInPage() {
  const router = useRouter();
  const searchParams = useSearchParams();

  const forcedRedirect = searchParams.get("forcedRedirect");

  useEffect(() => {
    if (forcedRedirect) {
      toast.error('Detected additional sessions, kicking you out');
      router.replace(ROUTE_PATHS.SIGNIN, undefined);
    }
  }, [forcedRedirect]);
  return (
    <SignIn />
  );
}

Notes

We detect if there's a searchParam called forcedRedirect
If there is we display a toast telling the user that they've been logged out
We also perform a router.replace to remove the query param on the URL to hide the search query.

Conclusion

By the end of this guide, you should have grasp on how to leverage Clerk's session management to prevent account sharing.

If there's any questions or remarks, feel free to leave it in the comments!

The full code to this guide is here

Consuming Video Resources

shun — Sun, 13 Dec 2020 04:14:09 +0000

Background

The learning process of a self-taught developer is time-consuming, from reading documentation to watching videos on how to build applications or a developer conference that usually lasts about 30 minutes or more. I find myself watching conference videos because they offer insights about a framework or optimizations that I would not figure out by reading through documentation.

While watching video provides resources, there is also a caveat of spending a large chunk of time on it. Additionally, viewing such videos makes me zone out after a while due to it being dry or too content-heavy. I needed a way to combat the time taken and zoning out.

Faster

After a while, I concluded that watching videos with an increased playback speed is the solution. Initially, this thought is filled with self-criticism such as not being able to comprehend what the speaker is saying however it is a worthy attempt.

Watching videos at 2x speed takes time to adjust to but once I passed the adjusting phase, I never looked back. I find myself not zoning out much due to the need of focusing on what the speaker is saying at a high playback speed. Additionally, being focused increase my comprehension of the videos.

Conclusion

Watching videos on a higher playback speed might not be for everyone, but it is worth a shot! Saving time and increasing comprehension is the main takeaway. With the extra time generated, I can devote it to doing other tasks or taking a longer break.

Give it a shot! Hope you enjoyed this post.

Squeezing time out of weekends

shun — Sat, 05 Dec 2020 03:37:24 +0000

In the beginning

Having only weekends to work on side projects, I was strapped for time. In an attempt to create more time during the weekends, I started waking up early in the weekends around 6 to 7 am. The temptation of lazing in bed is strong but the drive to generate time was stronger so I dragged myself out of bed and went on with the day.

Waking up early does not get easier even after a month, but I pressed on and got work done. However, being awake for long hours made me drained and prone to distraction. I scrolling through social media applications on my phone or watching youtube videos excessively, procrastinating at the task on hand. At the end of the day, I am left with little time to complete my work.

Taking Shape

Many weekends passed with me procrastinating, I decided that it needs to stop. Thus I wrote a guideline on what items that needs to be completed. Using Trello, I started to list down the tasks that need to be done and whenever I finished a task I would mark it as completed and move on to the next one. Having a guideline gave shape to my day but I was still distracted when dealing with daunting tasks such as debugging or planning out features which takes up a huge amount of time.

Experimenting

To prevent me from getting distracted while completing tasks, I began allocating 2 to 3 hours time frame for completing the task only to break when the task was finished. Initially, I can complete my tasks but overtime it increasingly got more difficult to focus.

When a large time frame did not work, I shifted to a smaller time frame of one-hour intervals but it was still difficult to focus. While desperately searching for a solution, I came across the Pomodoro technique which indicates that one will work for 25 minutes and rest for 5 minutes. The ideal amount of cycle to hit is 8 with break time incrementing up to 15 minutes.

Pomodoro Technique

Initially, I was skeptical about the time frame given to focus as it was only 25 minutes. After all writing code is all about immersing yourself in the lines and getting lost with time right? Well, I was never wrong more. The technique worked miracles, allowing myself to work for 25 minutes meant that I can have a laser focus on the task at hand and the short breather of 5 minutes allowed me to plan what I was going to do next.

Conclusion

Overall, I am very happy with the results that I have achieved with the Pomodoro technique. It has allowed me to complete my work at consistent pacing, speeding up the development process. Moreover, with break time I can reduce the fatigue that I faced previously while coding for long periods.

Additionally, at the end of the day, I will do a review of what I have done and written it down. This is to prove to myself that I have indeed done something during the day and did not waste it.

Hope you have enjoyed it!

Use Angular CLI to serve https locally

shun — Wed, 25 Nov 2020 06:20:10 +0000

Developing an angular application with HTTPS is useful, this is a guide outlining how to do it in a Linux environment.

Perquisites

angular-cli
mkcert

Setup

Initialize an angular application by running ng new https-dev in your terminal. Once the application is generated, change directory into it and create a folder called ssl . This will contain the certificates needed.

Optionally you can edit .gitignore to ignore this folder, preventing it from being committed.

Using mkcert

There are instructions on the page to guide you through installing mkcert regardless of your OS. With mkcert installed, run mkcert -install to generate a local Certificate Authority (CA) and restart your browser to make sure it registers the newly generated CA.

Firefox

Head to preferences and type in certificates in the search bar. Click on View Certificates and head to Authorities and locate mkcert development CA.

Chrome

Head to settings and type in certificates in the search bar. Scroll down to Manage certificates and head to Authorities and locate org-mkcert development CA.

Generating certificates

At the root of your project, run the following command:

$ mkcert -cert-file <folder/filename.pem> -key-file <folder/filename.pem> <space delimeted domain>
$ mkcert -cert-file ssl/local-cert.pem -key-file ssl/local-key.pem localhost 127.0.0.1 192.168.1.109 172.18.0.1 ::1 

Created a new certificate valid for the following names 📜
 - "localhost"
 - "127.0.0.1"
 - "192.168.1.109"
 - "localhost"
 - "172.18.0.1"
 - "::1"

The certificate is at "./ssl/local-cert.pem" and the key at ".ssl/local-key.pem" ✅

Development with https

To use the certificate we generated, use the following:

$ ng serve --ssl <boolean> --ssl-cert <path-to-cert> --ssl-key <path-to-key>
$ ng serve --ssl true --ssl-cert ./ssl/local-cert.pem --ssl-key ./ssl/local-key.pem

After the application is being served, check your address bar for the padlock. Indicating that localhost has https

Thank you for reading!!

Most of my time is not spent on writing code

shun — Tue, 02 Jun 2020 02:01:01 +0000

As some geek that likes to code, the development life cycle is vicious when there isn’t a clear goal or established plan. In an attempt to fix bugs or implement something from documentation, I find myself blindly fixing bugs or just copy-pasting code off the documentation hoping that it will work. Which doesn’t, leading me to an endless loop of trying to find the error and fix it. Blindly coding was what I used to spend most of my time on.

Until I stumbled upon something simple and yet effective, that is planning. With planning, this delicious pie represents how I spend my time when developing a website or a side project.

What is Planning?

For me, it is simply taking a piece of paper and writing out what I am going to develop, how it looks like, and the possible issues that I might face. It is like an artist who sketches on a canvas before drawing the image.

Why Planning?

Because it is essential to me, being able to write down my thoughts, brainstorming ideas, and have a visual guideline of what I am going to develop forces me to think. Think of the possible issues that I might run into and solutions for it. Also, it brings forward most of the debugging work that I will encounter. All these, are now written down with a pen and paper.

Aim for progress and not perfection. This is what I have learned while having a plan helps you outline what needs to be done it is not perfect. When writing a plan, it does not cover all the issues that we might encounter, which is why we have to adapt the plan as it is being written.

How to Plan?

Planning is like a puzzle. To gather the pieces, I have to brainstorm and write out all the ideas and possible implementations that are in my head. With the pieces in hand, I will begin to put them together, refining my plans by shifting the pieces around until I feel satisfied. Finally, it is time to assemble, I will start by trying to map out a flow and see if it makes sense.

If the final plan does not make sense, I will refine it until I feel good about it and most of the doubts I have are cleared. This ensures a close to smooth sailing experience when developing, as it potentially irons out most of the errors that might occur. Be it a logic flaw or a data structure model that just doesn’t make sense.

Conclusion

At the end of the day, we can’t escape from debugging or reading documentation as it is part of the development journey. But I believe that with a plan we can find ways to remove potential obstacles, reducing the time wasted on blindly coding.

What do we do with the time saved? For me, I spend that time debugging some random bug, refactor my code or knock off early and start doing some other things. For you, take that time to relax, learn a new hobby, or just have do something outside of work. Work != life.