mirror of https://github.com/brunopostle/ifcurl.git synced 2026-07-12 02:08:13 +00:00

Bruno Postle b23b210f76 Document git-wrapper for ifcmerge: Forgejo uses git merge-file not merge-tree

2026-05-17 23:37:14 +01:00

13 KiB

Raw Blame History

Forgejo integration

This directory contains assets for the ifcurl preview extension. The features split into two tiers by what infrastructure they require.

Feature overview

Feature	What it needs	Forgejo rebuild?
"View in 3D" button on file/history pages	`ifcurl.js` + ifcurl service	No
Browser IFC viewer	`viewer.html` static asset	No
PR diff 3D render	`ifcurl.js` + ifcurl service + Nginx proxy	No
`[title](ifc://...)` links in markdown → inline preview	`ifcurl.js` + ifcurl service + Nginx proxy	No
Bare `ifc://...` text in markdown → inline preview	`ifcurl.js` (JS text-node linkification)	No

All features work with static asset deployment only — no Forgejo rebuild required. ifcurl.js handles both <a href="ifc://..."> links produced by Goldmark's standard link parser and bare ifc://... text nodes, replacing both with preview figures at page load.

Bare URL caveat: bare ifc:// URLs where the path or query parameters contain matched underscores (e.g. _model_v2.ifc) may be split by Goldmark's emphasis parser before ifcurl.js can linkify them. Use the explicit [label](ifc://...) form in those cases — the viewer's Issue button always generates this safe form.

The PR diff feature requires a reverse proxy (e.g. Nginx) to expose the ifcurl service at the same origin as Forgejo. This is because the diff image is fetched by the browser (not by Forgejo's server), and browsers block cross-origin image requests to plain http://localhost URLs. Most production Forgejo deployments already sit behind Nginx for TLS termination; adding two proxy_pass lines is the only extra step.

Directory layout

forgejo/
  custom/public/assets/
    viewer.html                         ← browser IFC viewer (no rebuild needed)
    viewer-url.js                       ← ifc:// URL parse/build/resolve logic (ES module)
    viewer-util.js                      ← shared pure utilities: parseCommitHref, isSimpleTypeSelector, etc.
    ifcurl.js                           ← "View in 3D" + PR diff injection (ES module, no rebuild needed)
  templates/custom/
    footer.tmpl                         ← loads ifcurl.js (no rebuild needed)
  server-config/
    ifcurl-api.service                  ← systemd unit for the API service (git + caching)
    ifcurl-render.service               ← systemd unit for the render isolation service
    gitconfig-ifcmerge                  ← git merge driver registration for /etc/gitconfig
    gitattributes                       ← system-wide gitattributes for bare repos

Local setup (Windows + Docker)

For a self-contained local deployment of Forgejo + ifcurl on Windows using Docker, see SETUP_LOCAL.md.

Prerequisites

ifcurl API service + render service running (see Running the preview service)
Nginx (or equivalent) in front of Forgejo if PR diff images are wanted

No Forgejo source tree or Go toolchain is required — all features work with static asset deployment.

Building the viewer JavaScript bundle

The viewer loads Three.js, ThatOpen components, and JSZip from locally-bundled files rather than CDNs. The bundle files are committed to the repository, so you only need to re-run the build when upgrading a dependency version.

Prerequisites

Node.js 18+ and npm (used only at build time; not required on the server).

Run the build

cd forgejo/
npm install        # installs pinned versions from package-lock.json
npm run build      # produces the four files below
npm test           # run JavaScript unit tests (viewer-url.js, viewer-util.js)

Output files (committed to the repository):

File	Source	Purpose
`custom/public/assets/viewer-deps.js`	three + @thatopen/components + @thatopen/components-front + jszip	Main viewer dependencies
`custom/public/assets/fragments-worker.js`	@thatopen/fragments worker	IFC parsing web worker
`custom/public/assets/web-ifc.wasm`	web-ifc	IFC geometry kernel (single-threaded)
`custom/public/assets/web-ifc-mt.wasm`	web-ifc	IFC geometry kernel (multi-threaded)

The node_modules/ directory is gitignored and is never deployed.

Upgrading a dependency

Edit the version number in package.json, then:

cd forgejo/
npm install        # updates package-lock.json
npm run build      # regenerates the bundle from the new version
git add package.json package-lock.json custom/public/assets/
git commit -m "viewer: upgrade <package> to vX.Y.Z"

Deploying custom assets (no rebuild required)

These files can be updated at any time without recompiling Forgejo.

Viewer and URL logic

sudo mkdir -p /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/viewer.html          /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/viewer-url.js        /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/viewer-util.js       /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/viewer-deps.js       /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/fragments-worker.js  /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/web-ifc.wasm         /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/web-ifc-mt.wasm      /var/lib/forgejo/custom/public/assets/
sudo cp forgejo/custom/public/assets/ifcurl.js            /var/lib/forgejo/custom/public/assets/

ifcurl.js is an ES module and imports from viewer-util.js at the same path, so both files must be deployed together.

Served at /assets/viewer.html, /assets/viewer-deps.js, etc.

Note: the correct CustomPath is /var/lib/forgejo/custom (Forgejo's default when FORGEJO_CUSTOM is not set). Do not use /etc/forgejo/public/assets/ — Forgejo does not serve from there.

"View in 3D" footer template

sudo mkdir -p /var/lib/forgejo/custom/templates/custom/
sudo cp forgejo/templates/custom/footer.tmpl /var/lib/forgejo/custom/templates/custom/
sudo systemctl restart forgejo

Running the preview service

The service is split into two systemd units for security isolation:

ifcurl-api — handles HTTP requests, git fetching, and caching. Has network access and can call git CLI tools. Holds credentials (/etc/ifcurl/env). Delegates all IFC rendering to ifcurl-render over a Unix socket.
ifcurl-render — handles IFC parsing and rendering via ifcopenshell and pyvista. Has no network access, no credentials, and execve/execveat are blocked by systemd. Communicates only over the Unix socket.

This split limits the blast radius if a crafted IFC file achieves code execution in the render process: it cannot reach git hosts or read credentials.

As systemd services (recommended)

# Create the two service users
sudo useradd --system --no-create-home --shell /usr/sbin/nologin ifcurl
sudo useradd --system --no-create-home --shell /usr/sbin/nologin ifcurl-render

# Add ifcurl user to ifcurl-render group so it can read the socket
sudo usermod -aG ifcurl-render ifcurl

# Install the units (edit AllowedHosts and port in ifcurl-api.service first)
sudo cp forgejo/server-config/ifcurl-api.service    /etc/systemd/system/
sudo cp forgejo/server-config/ifcurl-render.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ifcurl-render
sudo systemctl enable --now ifcurl-api

Edit the ExecStart line in ifcurl-api.service to set your Forgejo hostname:

ExecStart=/usr/local/bin/ifcurl serve \
    --host 127.0.0.1 \
    --port 8000 \
    --allowed-hosts git.example.com

Cache limits and other environment variables for the API service go in /etc/ifcurl/env (one KEY=value per line):

IFCURL_CACHE_MAX_GB=10
IFCURL_T2_MAX=16

Render-side environment variables (timeouts, memory limits) go in /etc/ifcurl/render-env:

IFCURL_SANDBOX_TIMEOUT=180
IFCURL_SANDBOX_MEMORY_MB=2048

Single-service mode (testing / simple deployments)

Without IFCURL_RENDER_SOCKET set, the API service handles rendering directly in its own subprocess sandbox. This is simpler to set up but offers less isolation.

ifcurl serve --allowed-hosts git.example.com

For a Forgejo instance on a non-standard port (e.g. 3000 for local dev):

ifcurl serve --allowed-hosts localhost:3000

--allowed-hosts accepts a comma-separated list. Omitting it allows all non-private remote hosts, which is unsafe if the service is reachable from untrusted clients.

Nginx reverse-proxy for PR diff images

The PR diff viewer (Case 3 in footer.tmpl) injects <img src="/render_diff?…"> tags that the browser must fetch. The browser resolves /render_diff against the Forgejo origin, so the ifcurl service must be reachable at the public URL.

Add these proxy locations to the Nginx virtual host that fronts Forgejo:

# ifcurl preview service — served under the same origin as Forgejo
location /preview {
    proxy_pass         http://127.0.0.1:8000;
    proxy_set_header   Host $host;
    proxy_read_timeout 120s;
}

location /render_diff {
    proxy_pass         http://127.0.0.1:8000;
    proxy_set_header   Host $host;
    proxy_read_timeout 120s;
}

location /bcf {
    proxy_pass         http://127.0.0.1:8000;
    proxy_set_header   Host $host;
    proxy_read_timeout 120s;
}

Without this proxy the "View in 3D" button (Case 1/2) still works — it opens the viewer HTML which fetches the IFC file directly. The PR diff images (Case 3) will silently fail to load until the proxy is in place.

IFC merge driver (ifcmerge)

Configuring ifcmerge as the git merge driver for .ifc files lets Forgejo automatically merge IFC pull requests instead of marking them as conflicted.

How Forgejo checks mergeability

Forgejo checks PR mergeability by calling git merge-file current base other directly for each conflicting file. This command bypasses gitattributes merge drivers entirely — /etc/gitconfig and core.attributesFile have no effect on this code path.

The solution is a git wrapper at /usr/bin/git (with the original binary moved to /usr/bin/git.real) that intercepts merge-file calls, detects IFC files by their ISO-10303 STEP header, and delegates to ifcmerge instead.

The /etc/gitconfig merge driver registration and /etc/gitattributes are still useful for client-side git merge operations on developer machines, but they do not affect Forgejo's server-side conflict check.

Important: the git package in apt will overwrite /usr/bin/git on upgrade. Reinstall the wrapper (server-config/git-wrapper) after any git package upgrade.

Prerequisites

ifcmerge is a Perl script — install Perl's DateTime module first:

apt install -y libdatetime-perl

Then download ifcmerge from github.com/brunopostle/ifcmerge:

curl -o /usr/local/bin/ifcmerge \
  https://raw.githubusercontent.com/brunopostle/ifcmerge/main/ifcmerge
chmod +x /usr/local/bin/ifcmerge

Install the git wrapper

The git wrapper intercepts git merge-file for IFC files and routes them to ifcmerge. Install it by replacing the git binary:

mv /usr/bin/git /usr/bin/git.real
cp forgejo/server-config/git-wrapper /usr/bin/git
chmod +x /usr/bin/git

Deploy the config files (for client-side merges)

# System-wide gitattributes
sudo cp forgejo/server-config/gitattributes /etc/gitattributes

# Merge driver registration in /etc/gitconfig
sudo git config --system include.path /path/to/ifcurl/forgejo/server-config/gitconfig-ifcmerge

Or apply the blocks from server-config/gitconfig-ifcmerge directly into /etc/gitconfig by hand.

Merge direction

The invariant is that step-IDs in main/master must never be renumbered, because existing cross-references depend on them. The correct driver depends on which branch is the "local" (%A) side:

Situation	`%A` (local)	`%B` (remote)	Driver to use
Forgejo "Merge commit" button	`main`	PR branch	`ifcmerge_ours` (`--prioritise-local`)
Developer rebasing PR from `main`	PR branch	`main`	`ifcmerge` (default)

For Forgejo server-side merges, use the "Merge commit" strategy (not rebase or squash) and configure .gitattributes to use ifcmerge_ours:

*.ifc merge=ifcmerge_ours

ifcmerge (no flag) is for client-side use by developers updating their working branch from main, where main arrives as the remote (%B) side and its IDs are preserved by default.

Client-side `.gitattributes`

For client-side merges (git merge on a developer's machine) committed .gitattributes files in the repository work fine. It is still worth adding one:

*.ifc merge=ifcmerge

This ensures developers with ifcmerge installed get automatic IFC merges locally, and tools that read gitattributes (e.g. diff viewers) can identify .ifc files correctly.

Upgrading Forgejo

Custom assets (viewer.html, ifcurl.js, etc.) and footer.tmpl are unaffected by Forgejo upstream upgrades — redeploy them after each asset change and restart Forgejo once after updating footer.tmpl.

13 KiB Raw Blame History

Forgejo integration

Feature overview

Directory layout

Local setup (Windows + Docker)

Prerequisites

Building the viewer JavaScript bundle

Prerequisites

Run the build

Upgrading a dependency

Deploying custom assets (no rebuild required)

Viewer and URL logic

"View in 3D" footer template

Running the preview service

As systemd services (recommended)

Single-service mode (testing / simple deployments)

Nginx reverse-proxy for PR diff images

IFC merge driver (ifcmerge)

How Forgejo checks mergeability

Prerequisites

Install the git wrapper

Deploy the config files (for client-side merges)

Merge direction

Client-side .gitattributes

Upgrading Forgejo

13 KiB

Raw Blame History

Client-side `.gitattributes`