Skip to content

DEPLOY.md

Latest commit

 

History

History
222 lines (168 loc) · 5.88 KB

DEPLOY.md

File metadata and controls

222 lines (168 loc) · 5.88 KB
Raw

Self-hosting AnimCSS

This covers running AnimCSS on your own server, for any reverse proxy or tunnel setup.

Requirements

  • Node.js 20 or newer, or Bun 1.1+
  • A Linux server (or macOS/Windows) you can run a long-lived process on
  • Optionally, a Supabase project for the community catalog — see SUPABASE_SETUP.md. The editor itself works without it.

AnimCSS builds to a plain Node server (not a static site) because the community catalog's pages need server-side rendering for their metadata. The build target is already set correctly in vite.config.ts — you don't need to change anything for this.

1. Get the code onto the server

git clone <your-fork-or-repo-url> animcss
cd animcss

If you're not using git, copying the extracted project folder over (scp/sftp/rsync) works exactly the same — the steps below don't care how the files got there.

2. Install dependencies

npm install
# or: bun install

3. Configure environment variables

cp .env.example .env

Edit .env:

  • VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY — leave blank to run without the catalog, or fill in from SUPABASE_SETUP.md.
  • PORT — which port the server listens on (defaults to 3000 if unset).

These are read at build time, so re-run the build after changing them.

4. Build

npm run build
# or: bun run build

This produces .output/server/index.mjs (the app) and .output/public/ (static assets). Both are required at runtime — don't delete either.

5. Run it

npm run start
# equivalent to: node .output/server/index.mjs

By default it binds to all interfaces on the port from your .env (or 3000). Visit http://<server-ip>:<port>/ to confirm it's up before wiring a reverse proxy or tunnel in front of it.

Stop it with Ctrl+C. For anything beyond a quick test, run it under a process supervisor so it survives reboots and crashes — see the next section.

6. Keep it running with PM2

PM2 is the simplest way to keep a Node app alive across crashes and reboots.

npm install -g pm2
pm2 start deploy/ecosystem.config.cjs
pm2 save
pm2 startup   # follow the printed command once, so PM2 survives reboots
pm2 status
pm2 logs animcss

deploy/ecosystem.config.cjs also defines an animcss-webhook process — that one's optional, only needed if you set up the GitHub Webhook autoupdate method; PM2 won't start it unless you tell it to (pm2 start deploy/ecosystem.config.cjs --only animcss starts just the app).

Prefer systemd instead?

A unit file template:

[Unit]
Description=AnimCSS
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/opt/animcss
ExecStart=/usr/bin/node .output/server/index.mjs
EnvironmentFile=-/opt/animcss/.env
Environment=NODE_ENV=production
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

Save as /etc/systemd/system/animcss.service, fix User= and WorkingDirectory=, then:

sudo systemctl daemon-reload
sudo systemctl enable --now animcss
journalctl -u animcss -f

7. Putting a reverse proxy or tunnel in front of it

The app only speaks plain HTTP on one port — anything that can proxy to http://127.0.0.1:<port> works. A few common options:

Cloudflare Tunnel

No public inbound ports needed — cloudflared makes an outbound connection from your server to Cloudflare.

  1. Install cloudflared on the server (see Cloudflare's install docs for your distro).
  2. In the Zero Trust dashboard → Networks → Tunnels → Create a tunnel → Cloudflared → name it → copy the cloudflared service install <token> command it gives you and run it on the server.
  3. Back in the dashboard, Public Hostname → Add a public hostname: pick your subdomain/domain, Service Type HTTP, URL localhost:<port>.
  4. If your domain isn't already using Cloudflare's nameservers, it won't appear in the domain dropdown — either point the domain's nameservers at Cloudflare (unlocks the dropdown), or add a CNAME record yourself, wherever that domain's DNS actually lives, pointing at <tunnel-id>.cfargotunnel.com (shown on the tunnel's overview page).
Caddy 
your-domain.com {
    reverse_proxy 127.0.0.1:3004
}

Caddy handles HTTPS certificates automatically.

nginx 
server {
    listen 443 ssl;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3004;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

(Add your own TLS cert config/certbot block — omitted here since it's identical to any other nginx site.)

Updating

git pull
npm install
npm run build
pm2 restart animcss

If you'd rather this happen automatically whenever you push a commit, see AUTOUPDATE.md — a GitHub Webhook listener that runs exactly these steps for you.

Troubleshooting

  • Blank page / 404 on every route: usually means .output/public is missing or the build failed silently — check npm run build output for errors before it exits 0.
  • Catalog pages say "not configured": VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY weren't set at build time, or the build wasn't re-run after setting them.
  • Port already in use: something else is already listening on that port — change PORT in .env and rebuild, or free up the port.