Client-only install

Run Linkr in the browser alone, with Node.js: no backend, no accounts, and publishable as a static site.

Summary

The lightest method: Node.js alone, no backend, no database, no accounts. Everything runs in the browser. In exchange, no remote warehouse, no Git versioning and no sharing between users. It is the right choice to discover Linkr, work on local files on your own, or publish an instance as a static site.

Requirements

Node.js 20+ and npm (nodejs.org).
Git, and Git LFS to fetch the demo data.
About 1 GB of disk space.

Installation

The commands are the same on macOS, Linux and Windows.

Clone the repository

git clone https://framagit.org/interhop/linkr/linkr.git
cd linkr

Install dependencies

Anywhere from a few dozen seconds to 2 minutes.

npm install

Start Linkr

Then open http://localhost:3000.

npm run dev:web

You're set

Linkr is running in your browser. The sections below are there when you need them: demo data, publishing as a static site, troubleshooting.

Getting the demo data

The demo dataset (the MIMIC-IV demo database and the example projects) is not in the repository, and npm run dev:web does not fetch it, so no network is required. Run this command once to add it to your local instance:

npm run data:fetch

What client-only mode enables, and what it does not, is detailed in Deployment modes.

Publishing as a static site

Two commands, from the repository root. The first bakes the demo dataset into the site; without it, the published instance starts empty. The second compiles the app into static files ready to deploy:

npm run data:fetch
npm run build:client

build:client forces client-only mode, even when an apps/web/.env.local sets VITE_API_URL: that is what keeps you from publishing a site that waits for a server and shows nothing but a login page.

The output lives in apps/web/dist/. You can upload it as-is to:

GitLab Pages: through .gitlab-ci.yml (an example is provided in the repo).
GitHub Pages: push the contents of dist/ to a gh-pages branch.

Linkr handles its addresses in the browser: a direct link to a project matches no file in the folder. On GitLab or GitHub Pages, copy index.html to 404.html (the repository’s .gitlab-ci.yml does it); on nginx, send unknown paths to index.html (try_files $uri /index.html;).

Netlify / Vercel / Cloudflare Pages: connect the repository and point the build output to apps/web/dist.
Classic web server (nginx, Apache): copy dist/ to the served folder.

To check the result before uploading it, npm run preview (still in apps/web) serves the build locally.

Serve over HTTPS

DuckDB-WASM and some modern APIs (File System Access) require a secure context: HTTPS, or HTTP only on localhost. If you host Linkr on a domain, enable HTTPS.

Troubleshooting

npm install fails. Check that you are on Node.js 20+ (node -v). If you have several Node.js versions, run nvm use 20.

Port 3000 is busy. The dev script usually offers another port automatically, or close the process that holds it (lsof -i :3000 on macOS/Linux).

The app shows a login page. That means VITE_API_URL is set, usually in apps/web/.env.local (created by the manual install). Empty it, or run npm run dev:client, which forces client-only mode.

The build is very large. That’s expected in client-only mode: the DuckDB-WASM, Pyodide and webR runtimes weigh several MB each. They are loaded on demand by the browser, not all at once.

Next steps

Move to server mode, with accounts and a warehouse: Install with Docker.
Build your first project: Your first project.