Local install

Install and run Linkr on your own machine, to develop or host your own instance.

Summary

In client-only mode, all you need is Node.js 20+ and three commands to get a working local Linkr instance. No backend, no database to configure. You can then publish the result as a static site on GitLab Pages, GitHub Pages or any other hosting.

Client-only

Full-stack backend install will be documented incrementally.

Prerequisites

Node.js 20+ and npm. Install from nodejs.org or via a version manager such as nvm.
Git to clone the repository.
About 1 GB of disk space (mostly for node_modules).
A modern browser: recent Firefox, Safari, Chrome or Edge.

Why Node.js if everything runs in the browser?

Node.js is only used during development: to install dependencies, run the dev server (Vite) and produce the static build. Once compiled, the app no longer needs Node.js: it deploys as a plain static site.

Run Linkr locally

Clone the repository

The repo is hosted on FramaGit. Clone it over HTTPS or SSH, then step into the project folder.

# HTTPS
git clone https://framagit.org/interhop/linkr/linkr.git
# or SSH (if your key is configured)
git clone git@framagit.org:interhop/linkr/linkr.git
cd linkr

Install dependencies

From the monorepo root, npm install fetches and installs dependencies for every workspace (apps/web, packages/default-plugins, etc.). This step takes 1–2 minutes on first run.

npm install

Start the dev server

The frontend starts on http://localhost:3000. Hot reload is enabled: every change to a source file is reflected instantly in the browser, without a restart.

npm run dev:web

Build for production

This command compiles the app into a set of static files ready to deploy. The output lives in apps/web/dist/ — that's the folder you upload to your hosting.

cd apps/web
npm run build

Deploy as a static site

Once apps/web/dist/ is built, 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.
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.

Serve over HTTP or 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.

Using Docker

Work in progress

The docker/ folder in the repo contains Dockerfiles and a docker-compose.yml, but this setup is not yet validated. It will be documented here once full-stack mode stabilises. In the meantime, use the local dev workflow described above.

Repository layout

The repo is a Turborepo monorepo:

apps/web/ — React + Vite frontend (the main app).
apps/api/ — FastAPI backend (under development).
packages/default-plugins/ — default analysis plugins (Table 1, Plot Builder, etc.).
docker/ — Docker configurations.
docs/ — internal project documentation (different from the user documentation you’re reading here).

Useful commands

Command	Effect
`npm install`	Install all monorepo dependencies.
`npm run dev:web`	Start frontend in dev mode (port 3000).
`npm run build`	Produce production build for all workspaces.
`cd apps/web && npm run preview`	Serve the production build locally.

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 build is very large. That’s expected: 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

Build your first project: Your first project.
Understand the difference between the two modes: Deployment modes.