English · 한국어
A real-time block editor for a team on one local network — no cloud service, no accounts.
One person, the host, runs RMF-Block as a Docker container. Everyone else on the same subnet opens a link in their browser, joins with a nickname and the workspace password, and edits the same documents together. CBNU Team H capstone project.
The host machine runs three containers: the app — a Next.js custom server for pages, REST and
WebSockets — and a self-hosted Yorkie server with MongoDB behind it. Yorkie
syncs every document as a CRDT and keeps its content and history; the app keeps its own state as
JSON under .data/. Documents, chat and uploaded files are stored on the host and shared over
the LAN.
ARCHITECTURE.md has the diagram; docs/design/architecture.md
the contracts.
You need Docker with Compose 2.20 or newer — nothing else: no clone, no Node.js. Each release runs a published image built for both x86-64 and Apple Silicon.
On Linux or macOS:
mkdir rmf-block && cd rmf-block
curl -LO https://github.com/CBNU-TeamH/RMF-Block/releases/latest/download/docker-compose.yml
curl -L -o .env https://github.com/CBNU-TeamH/RMF-Block/releases/latest/download/env.sampleOn Windows PowerShell 5.1:
mkdir rmf-block
Set-Location rmf-block
curl.exe -LO https://github.com/CBNU-TeamH/RMF-Block/releases/latest/download/docker-compose.yml
curl.exe -L -o .env https://github.com/CBNU-TeamH/RMF-Block/releases/latest/download/env.sampleSet HOST_LAN_IP in .env to this machine's IPv4 address on the guests' LAN. Each command
below prints the address of the connection your machine uses to reach the internet, which is
usually that one. Run it on the host machine, outside the containers:
Windows (PowerShell, in Windows rather than WSL):
(Get-NetIPConfiguration | Where-Object IPv4DefaultGateway).IPv4Address.IPAddressLinux — the address after src:
ip -4 route get 1.1.1.1macOS:
ipconfig getifaddr "$(route -n get default | awk '/interface:/{print $2}')"Nothing is sent to 1.1.1.1; the command only asks which route would be used. If it prints
nothing, or a VPN address because a VPN is on, list every address instead — ipconfig on
Windows, ip -4 addr show scope global on Linux, networksetup -listallhardwareports and then
ipconfig getifaddr <device> on macOS — and take the Wi-Fi or Ethernet adapter's IPv4 address.
Docker, WSL, VPN and loopback interfaces may be listed too; they are not the one.
For example, if the LAN address is 192.168.0.14, save this in .env (use your own address,
not this example):
HOST_LAN_IP=192.168.0.14For this Docker setup, set HOST_LAN_IP here and the two Yorkie values below, and leave the
other sample settings as supplied. Choose the workspace name and password in the browser after startup.
The commented Yorkie addresses are for native development; Compose supplies its
own internal addresses and does not use those values from .env.
From a clone, pnpm docker:up detects it and writes .env
(scripts/detect-host-ip.sh, not part of a release). If the
address changes, update .env and run docker compose up -d again; a DHCP reservation for the
host on the router keeps it from changing.
Port 8080 also serves Yorkie's admin API, and Yorkie's built-in defaults would let anyone on the
LAN read or delete every document, so Compose refuses to start until .env has two values of your
own. Nobody types them in — they are for Yorkie and the app.
YORKIE_ADMIN_PASSWORD: 8 to 30 characters with letters, digits and a symbol such as-. Keep it once set: Yorkie stores it in its volume, and a different value later stops the app from starting.YORKIE_ADMIN_TOKEN_SECRET: any long random string. It signs Yorkie's admin logins; changing it later only signs those out.
YORKIE_ADMIN_PASSWORD=choose-your-own-1
YORKIE_ADMIN_TOKEN_SECRET=any-long-random-string-of-your-ownFrom a clone, pnpm docker:up generates both when they are empty.
Guests connect to TCP 3000 (the app) and TCP 8080 (Yorkie, which carries the live edits). A page that opens but never shows edits usually means 8080 is blocked.
- Windows: set the Wi-Fi or Ethernet network's profile to Private, and allow Docker
Desktop when Windows Defender Firewall asks. If it did not ask, add a rule in PowerShell run as
administrator:
New-NetFirewallRule -DisplayName "RMF-Block" -Direction Inbound -Protocol TCP -LocalPort 3000,8080 -Action Allow -Profile Private - macOS: if the firewall is on (System Settings → Network → Firewall), allow incoming connections for Docker.
- Linux: if
ufwis active,sudo ufw allow 3000,8080/tcp.
docker compose upAmong the startup output are these two lines:
rmf-app | Host: http://localhost:3000/api/auth/host?secret=…
rmf-app | Guest: http://192.168.0.14:3000
- Open the
Host:link yourself. It makes you the host and drops the secret from the address bar. Treat the line as a credential: it stays valid until the container restarts. - The first time, it opens the setup screen. Choose the workspace name and the access password
there, then tell guests the password. Until then the startup output says
host user의 workspace setting이 완료되지 않았습니다.and guests cannot join. The 관리자 link (with a shield) at the foot of the sidebar, shown only to the host, is where you change the password later or remove a guest. The settings persist on the volume — emptying.envdoes not reset them; startup printsWorkspace "<name>" — saved settings …when they exist. To see the setup screen again, stop the stack and deleteworkspace.jsonfrom theapp-datavolume. - Give everyone else the
Guest:address. - Restarting the container signs everyone out; removing one guest is the admin page's 퇴장
(
docs/design/api.md). - Documents and app state survive restarts and upgrades on named volumes — members keep their
colours — and
docker compose down -vwipes them.
Download the new release's docker-compose.yml over the old one, keep .env, and run:
docker compose pull && docker compose up -dOn Windows PowerShell 5.1, run up only if pull succeeds:
docker compose pull
if ($LASTEXITCODE -eq 0) { docker compose up -d }From 0.0.1: add both Yorkie values to .env first (Set the Yorkie admin
secrets). The first start moves Yorkie's existing administrator off
admin/admin onto YORKIE_ADMIN_PASSWORD.
The documents and settings stay when the Compose project name stays the same. The release file
defaults to rmf-block; an older installation may have used its folder name instead.
Switching an existing clone to a release: before changing folders or removing containers, find the current project name. On Linux or macOS:
docker inspect rmf-app --format '{{ index .Config.Labels "com.docker.compose.project" }}'On Windows PowerShell 5.1:
docker inspect rmf-app | ConvertFrom-Json | ForEach-Object { $_.Config.Labels.'com.docker.compose.project' }Download the new release's docker-compose.yml into a separate folder and copy your existing
.env there, keeping HOST_LAN_IP and the other settings. Do not download env.sample over it.
Set COMPOSE_PROJECT_NAME in the copied .env to the name printed above, for example:
COMPOSE_PROJECT_NAME=rmf-blockRun the upgrade commands from that folder. It must contain no docker-compose.override.yml,
because a clone's override selects a source build. Keeping the project name reuses the existing
containers and the app-data and mongo-data volumes. docker compose down alone does not
move data between project names; changing the name selects different volumes. Do not use
down -v, which deletes them.
Rolling back: put the previous release's docker-compose.yml back in the folder and run the
same upgrade commands; the volumes stay. A newer version may have changed what it stores, which an
older one cannot always read, so back up the app-data and mongo-data volumes before upgrading.
Each release's file names its own version. To pin the exact image, append the digest from the
release notes (…:0.0.1@sha256:…). Use that one and not a digest from the package page, which pins
a single architecture.
Test from another device on the LAN — a phone works — by opening the Guest: address. Opening it
on the host proves nothing about the network. If it fails, check in this order:
- Client/AP isolation. Campus and guest Wi-Fi often block devices from reaching each other even on one network. It is a router setting no script here can detect; try a phone hotspot or another network to rule it out.
- Ports and firewall. Both 3000 and 8080 must be open (Open the ports).
- Windows hosts. Docker Desktop's WSL2 backend may forward the port only to
127.0.0.1. From a clone,pnpm docker:upchecks whether WSL mirrored networking is enabled and prints configuration guidance. Mirrored networking needs Windows 11 22H2+; on older Windows, forward the port to the host's LAN address yourself (netsh interface portproxy). - Wrong address in the
Guest:line: see Set the host's LAN address.
| Read | For |
|---|---|
AGENTS.md |
The working rules — workflow, coding principles, which doc answers what |
docs/SRS-ko.md · docs/SRS-en.md |
Requirements: the agreed Korean text and its English translation |
docs/design/ · docs/adr/ |
Module design and architecture decisions |
ROADMAP.md |
What is built and what comes next |
See CONTRIBUTING.md for the development setup, the checks, and how a change
becomes a pull request.
MIT. The bundled Pretendard font is under the SIL Open Font License 1.1
(app/fonts/PretendardVariable.LICENSE.txt).



