This quickstart guide will walk through the process of self-hosting magiclinksdev on your local machine.

The quickstart configuration will use a no-operation email sender and robots will not be prevented from following magic links. For details on how to do more advanced configuration, please visit the Configuration docs.


This example requires Go, Git, and Docker to be installed on your machine.

Please note, earlier versions of Docker Compose used the command docker-compose rather than docker compose. If you are using an older version, please translate the commands accordingly.

The following Docker images will be pulled by Docker Compose automatically.

  • micahparks/magiclinksdevnop:latest
  • postgres:15

Step 1: Clone the repository

The files and directories used in this quickstart are:

  • docker-compose.quickstart.yml
  • docker-compose.override.yml
  • config.quickstart.json
  • storage/postgres/startup.sql
  • examples/client/send_link/
git clone https://github.com/MicahParks/magiclinksdev.git
cd magiclinksdev

Step 2: Use Docker Compose

Launch the service and its database in the background using Docker Compose.

docker compose up -d

The example from the repository in examples/client/send_link/ will request a magic link from the service. This magic link should redirect to jwtdebug.micahparks.com with a URL query parameter jwt containing a JWT.

go run examples/client/send_link/main.go

The output should look similar to this:

  "linkCreateResults": {
    "magicLink": "http://localhost:8080/redirect/?secret=66af8a5d-7e8d-4f9f-9729-161e214c7d1c",
    "secret": "66af8a5d-7e8d-4f9f-9729-161e214c7d1c"
  "requestMetadata": {
    "uuid": "b56640e4-242d-4bbf-a7b5-1c678502eb5d"

By default, the link will only be valid for 5 minutes. Copy the magic link and open it in a browser. You should be redirected to jwtdebug.micahparks.com with a signed JWT in a URL query parameter. This website is a slimmed down version of the jsonwebtoken.github.io GitHub project.


  "alg": "EdDSA",
  "kid": "526ff60f-9c8b-4a73-ba74-cc8962494873",
  "typ": "JWT"


  "foo": "bar",
  "iss": "http://localhost:8080",
  "aud": [
  "exp": 1673815954,
  "nbf": 1673815654,
  "iat": 1673815654,
  "jti": "1a1e2abe-b467-4bf6-9194-c4a60c54745b"

Step 5: Cleanup

Stop the service and the database from running in the background.

docker compose down


Please note that the quickstart configuration should not be used in production. It is essential to regenerate all UUIDs, especially the admin API key. Additionally, a new storage AES-256-GCM key should be generated.

Any UUIDs and storage AES-256-GCM keys should be generated with sufficient entropy. On Linux systems the following commands can accomplish this:

Generate a random UUID on Linux

uuidgen --random

Generate a AES-256-GCM key on Linux

openssl rand -base64 32


You have successfully self-hosted magiclinksdev on your local machine! You can now configure the service for your use case and request magic links for your own applications. See the Configuration reference for more information.