Self-Hosting Guide

The svg2nametag-Ren web app is a static site that can be hosted on any modern web server (Nginx, Apache, Caddy) or static hosting service (GitHub Pages, Netlify, Vercel).

Prerequisites

Node.js: Version 18 or higher.
npm or yarn.

1. Build the Application

Before deploying, you must generate the optimized production build:

cd webapp
npm install
npm run build

This will create a dist folder containing the compiled HTML, JavaScript, CSS, and the required WebAssembly (WASM) files.

2. Server Configuration

The app uses WebAssembly (WASM) for geometry processing. Your web server must serve .wasm files with the correct MIME type: application/wasm.

Nginx Example

Add this to your server block:

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/svg2nametagRen/webapp/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Ensure WASM files are served correctly
    location ~* \.wasm$ {
        default_type application/wasm;
        add_header Cache-Control "public, max-age=31536000";
    }
}

Static Hosting (GitHub Pages / Netlify)

Most modern static hosts (Netlify, Vercel, GitHub Pages) automatically handle .wasm MIME types correctly. Simply point the "Publish Directory" to webapp/dist.

3. Local Hosting (Preview)

If you want to host the production build locally to test it:

npm run preview

4. Troubleshooting

WASM Initialization Errors

If the app loads but fails to process SVGs with a "WASM loading" error:

Check the browser console.
Ensure manifold.wasm is present in the root of your deployment folder.
Verify that your server isn't blocking .wasm files or serving them as text/plain.

Path Issues

If you are hosting the app in a subfolder (e.g., https://example.com/nametag/), you must update the base configuration in webapp/vite.config.js:

export default defineConfig({
  base: '/nametag/', // Add this line
  plugins: [react()],
})

5. Containerization (OCI / Docker)

A Dockerfile is provided in the webapp directory for easy deployment using Docker or Podman.

Build and Run

cd webapp
docker build -t nametag-web .
docker run -d -p 8080:80 nametag-web

The app will be available at http://localhost:8080.

Docker Compose

Create a docker-compose.yml in the root directory:

services:
  nametag-web:
    build: ./webapp
    ports:
      - "8080:80"
    restart: unless-stopped

CLI via Docker

If you prefer not to install Python locally, you can use the CLI via its own Dockerfile:

# Build the CLI image
docker build -t nametag-cli -f Dockerfile.cli .

# Run the conversion (mounts local directories into the container)
docker run --rm \
  -v /path/to/your/svgs:/input \
  -v /path/to/output:/output \
  nametag-cli /input --output-dir /output

6. LXC (Linux Containers)

LXC is ideal for hosting on Proxmox or standard Linux servers where you want a lightweight system container.

Manual Setup (Debian/Ubuntu LXC)

Create the container (e.g., using pct on Proxmox or lxc-create).

Install Nginx and Node.js:

apt update && apt install -y nginx nodejs npm

Deploy the code: Clone the repo inside the LXC or copy the dist folder to /var/www/html.
Configure Nginx: Use the Nginx configuration provided in Section 2.
Permissions: Ensure www-data has access to the files:
```
chown -R www-data:www-data /var/www/html
```

Proxmox Helper Script (Optional)

If you use Proxmox, you can use a generic Nginx LXC and simply rsync the webapp/dist folder into it.