Skip to content

About

A type-safe implementation of the RealWorld spec, featuring a Haskell Servant backend and frontend using 'react-tea-cup'

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

RealWorld FullStack Monorepo

AI-DECLARATION: assist

A production-grade, type-safe implementation of the RealWorld spec, featuring a Haskell Servant backend and React frontends built with The Elm Architecture (TEA) using react-tea-cup and Tailwind CSS v4.

Live demo: https://conduit.rinn7e.com/. It also has an admin dashboard at /admin/ and API docs at /swagger-ui.

Project Structure

Quick Start (Run All Services)

Launch all services simultaneously in a tmux session:

# Start all 5 services (Backend, Showcase, Web, Admin, Admin Legacy) in tmux
cd package/backend && make server

# Or start with a fresh database reset:
cd package/backend && make server-fresh

Services Overview:

Service Location Port / URL
Backend API package/backend http://localhost:3000
Frontend Web package/frontend-web http://localhost:5173
Frontend Admin package/frontend-admin http://localhost:5174
Design System Showcase package/frontend-design-system/app/showcase-app http://localhost:5175
Frontend Admin Legacy package/frontend-admin-legacy http://localhost:5176
iOS Admin package/mobile-admin-ios iOS Simulator or an iPhone (see its README)
Android Admin package/mobile-admin-android Android emulator or a phone (see its README)
CLI Admin package/cli-admin pnpm dev in a terminal (see its README)

Deployment (Docker + GitHub Actions + VPS)

Live demo: https://conduit.rinn7e.com/. The site at / is the web app, /admin/ is the admin dashboard, and /swagger-ui has the API docs.

This section explains how to run the production image locally and how to deploy your own copy to a Linux server with automatic HTTPS and CI/CD.

How it works

git push master ─▶ GitHub Actions (.github/workflows/deploy.yml)
                     1. build ONE image (docker/app.Dockerfile): Haskell server + frontend-web + frontend-admin
                        → ghcr.io/<owner>/<repo>:latest and :<commit-sha>
                     2. deploy over SSH: pull on the server → migrate-exe up → docker compose up --wait
server ─ caddy-front (HTTPS :443, github.com/rinn7e/caddy-front)
           └─ docker network "proxy" ─▶ app :3000 (serves /, /admin, /api, /swagger-ui) ─▶ db (Postgres 18, volume)
  • One image. The Haskell server serves both frontends itself (FRONTEND_WEB_DIR, FRONTEND_ADMIN_DIR), next to /api and the swagger UIs.
  • HTTPS is handled elsewhere. It's not part of this repo: caddy-front, a small shared reverse proxy, owns port 443 and the certificates, so several projects can share one server. This project only joins its proxy network and registers DOMAIN with labels, in docker-compose.vps.yml.
  • The database holds user data. Deploys only run pending migrations. They never reset or reseed it. Back it up with pg_dump (see package/backend/README.md).
  • Compose files:
    • docker-compose.yml is the app and database, with no ports published.
    • docker-compose.override.yml is for local use and loaded automatically. It serves http://localhost:3000.
    • docker-compose.vps.yml is for the server only. It's enabled by COMPOSE_FILE=docker-compose.yml:docker-compose.vps.yml in the server's .env.
  • @rinn7e/tea-cup-* packages come from GitHub Packages. Its npm registry requires a login even for public packages, so create a GitHub personal access token (classic) with the read:packages scope and export it as INSTALL_GITHUB_PACKAGE_TOKEN in your shell.

Run the production stack locally

Requirements: Docker, plus INSTALL_GITHUB_PACKAGE_TOKEN in your shell.

cp .env.example .env                        # then add IMAGE_TAG=localtest
docker compose build                        # builds ghcr.io/...:localtest (never pushed)
docker compose up -d --wait db
docker compose run --rm app /app/migrate-exe up
docker compose up -d --wait                 # http://localhost:3000 and http://localhost:3000/admin/

To load the demo data (users, articles; every password is testtest) into the fresh database:

docker compose exec -T db psql -U postgres -d realworld < package/backend/resource/seed.sql

Deploy your own copy

You need:

  • A fork of this repository. Its CI publishes the image to ghcr.io/<your-account>/<repo>.
  • An x86_64 Linux server with a public IP. 1 GB RAM plus swap is enough.
  • A domain name. One A record for the site, e.g. realworld.example.com.

1. Prepare the server (once). Follow caddy-front: its README sets up swap, the firewall (SSH + 443) and Docker, then starts the proxy. Then let the server pull your private image:

ssh root@<server-ip> docker login ghcr.io -u <github-username>    # password: a PAT with read:packages

2. DNS. Add an A record for your domain pointing at the server IP. On Cloudflare, set it to DNS only (grey cloud).

3. Create the server .env (from your computer, in this repo):

echo "VPS_TARGET=root@<server-ip>" >> .env
make vps-env        # asks for DOMAIN; sets IMAGE from your git remote; generates POSTGRES_PASSWORD, JWT_SECRET

make vps-env refuses to overwrite an existing .env, because the database keeps the password it was created with. To change one value later, use make vps-set-env -- KEY [VALUE].

4. Let GitHub Actions deploy over SSH. Use a dedicated key, so your personal key never goes to GitHub:

ssh-keygen -t ed25519 -N "" -C "github-actions-deploy" -f ~/.ssh/realworld_deploy
# -f is required: without it ssh-copy-id test-logs in with your personal key and skips this one
ssh-copy-id -f -i ~/.ssh/realworld_deploy.pub root@<server-ip>

gh secret set VPS_SSH_KEY < ~/.ssh/realworld_deploy
ssh-keyscan <server-ip> | gh secret set VPS_KNOWN_HOSTS    # pins the server's host key
gh secret set VPS_HOST --body <server-ip>
gh secret set VPS_USER --body root
gh secret set VPS_DIR --body realworld                     # folder on the server (~/realworld)
gh secret set INSTALL_GITHUB_PACKAGE_TOKEN                 # the read:packages PAT, for the @rinn7e/tea-cup-* install

5. Deploy. Push to master, or run Build & Publish Docker Image from the Actions tab. CI builds the image, pushes it, runs migrations on the server and starts the app. Only pushes that change the app trigger it (see paths: in the workflow), and a weekly run keeps the build cache warm without deploying.

6. (Optional) Load the demo data once, into the still-empty database:

ssh root@<server-ip> 'cd realworld && docker compose exec -T db psql -U postgres -d realworld' < package/backend/resource/seed.sql

Day to day

Command What it does
make vps-deploy Manual deploy of :latest: copy the compose files, pull, migrate, restart
make vps-set-env -- KEY [VALUE] Change one value in the server .env and apply it. With no VALUE it prompts, which you need for values with $ or spaces
make vps-set-env -- IMAGE_TAG <old-sha> Roll back to an older commit's image (the next push deploys its own commit again)
make docker-up / make docker-down Start / stop the production stack locally

All make vps-* commands use VPS_TARGET from your local .env. Override it with make vps-deploy -- root@<other-ip>.

Individual Package Documentation

For details on running individual packages independently:

Sponsors

A heartfelt thank you to the sponsors supporting this project 😁:

AI declaration

This project declares its AI usage in AI-DECLARATION.md, following the AI-DECLARATION.md standard (level: assist).

License

This project is licensed under the MIT License.

About

A type-safe implementation of the RealWorld spec, featuring a Haskell Servant backend and frontend using 'react-tea-cup'

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages