{
  "slug": "install/bare-metal",
  "title": "Install on bare metal",
  "description": "Run Cuitty as a single Bun binary on a Linux VM, with systemd-managed services for production durability.",
  "url": "https://cuitty.com/docs/install/bare-metal",
  "markdown_url": "https://cuitty.com/docs/install/bare-metal.md",
  "json_url": "https://cuitty.com/docs/install/bare-metal.json",
  "frontmatter": {
    "title": "Install on bare metal",
    "description": "Run Cuitty as a single Bun binary on a Linux VM, with systemd-managed services for production durability.",
    "order": 3,
    "section": "Install",
    "updatedAt": "2026-04-27"
  },
  "headings": [
    {
      "depth": 1,
      "slug": "install-on-bare-metal",
      "text": "Install on bare metal"
    },
    {
      "depth": 2,
      "slug": "prerequisites",
      "text": "Prerequisites"
    },
    {
      "depth": 2,
      "slug": "download",
      "text": "Download"
    },
    {
      "depth": 2,
      "slug": "configure",
      "text": "Configure"
    },
    {
      "depth": 2,
      "slug": "systemd-unit",
      "text": "systemd unit"
    },
    {
      "depth": 2,
      "slug": "reverse-proxy",
      "text": "Reverse proxy"
    }
  ],
  "body_markdown": "# Install on bare metal\n\nCuitty ships a single Bun-bundled binary suitable for running directly on a Linux VM without containers. This is the lowest-overhead deployment option.\n\n## Prerequisites\n\n- Linux x86_64 or arm64\n- Postgres 15+ (local or remote)\n- A SpiceDB binary on `PATH`\n- Bun 1.3+ (only required to rebuild from source)\n\n## Download\n\n```bash\ncurl -fsSL https://releases.cuitty.com/portal/latest/portal-linux-x86_64 \\\n  -o /usr/local/bin/cuitty-portal\nchmod +x /usr/local/bin/cuitty-portal\n```\n\n## Configure\n\nCreate `/etc/cuitty/portal.env`:\n\n```dotenv\nDATABASE_URL=postgres://cuitty@localhost/cuitty\nSPICEDB_URL=localhost:50051\nSPICEDB_TOKEN=...\nBETTER_AUTH_SECRET=...\nPORT=7700\nDATA_DIR=/var/lib/cuitty\n```\n\n## systemd unit\n\n`/etc/systemd/system/cuitty-portal.service`:\n\n```ini\n[Unit]\nDescription=Cuitty Portal\nAfter=network.target postgresql.service\n\n[Service]\nType=simple\nEnvironmentFile=/etc/cuitty/portal.env\nExecStart=/usr/local/bin/cuitty-portal\nRestart=on-failure\nUser=cuitty\nGroup=cuitty\nWorkingDirectory=/var/lib/cuitty\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsystemctl daemon-reload\nsystemctl enable --now cuitty-portal\n```\n\n## Reverse proxy\n\nRun Caddy or nginx in front of the portal for TLS termination. The portal expects to be reached over HTTPS in production for cookie-based auth to work correctly.",
  "body_html": "<h1 id=\"install-on-bare-metal\">Install on bare metal</h1>\n<p>Cuitty ships a single Bun-bundled binary suitable for running directly on a Linux VM without containers. This is the lowest-overhead deployment option.</p>\n<h2 id=\"prerequisites\">Prerequisites</h2>\n<ul>\n<li>Linux x86_64 or arm64</li>\n<li>Postgres 15+ (local or remote)</li>\n<li>A SpiceDB binary on <code>PATH</code></li>\n<li>Bun 1.3+ (only required to rebuild from source)</li>\n</ul>\n<h2 id=\"download\">Download</h2>\n<pre class=\"astro-code github-dark\" style=\"background-color:#24292e;color:#e1e4e8; overflow-x: auto;\" tabindex=\"0\" data-language=\"bash\"><code><span class=\"line\"><span style=\"color:#B392F0\">curl</span><span style=\"color:#79B8FF\"> -fsSL</span><span style=\"color:#9ECBFF\"> https://releases.cuitty.com/portal/latest/portal-linux-x86_64</span><span style=\"color:#79B8FF\"> \\</span></span>\n<span class=\"line\"><span style=\"color:#79B8FF\">  -o</span><span style=\"color:#9ECBFF\"> /usr/local/bin/cuitty-portal</span></span>\n<span class=\"line\"><span style=\"color:#B392F0\">chmod</span><span style=\"color:#9ECBFF\"> +x</span><span style=\"color:#9ECBFF\"> /usr/local/bin/cuitty-portal</span></span></code></pre>\n<h2 id=\"configure\">Configure</h2>\n<p>Create <code>/etc/cuitty/portal.env</code>:</p>\n<pre class=\"astro-code github-dark\" style=\"background-color:#24292e;color:#e1e4e8; overflow-x: auto;\" tabindex=\"0\" data-language=\"dotenv\"><code><span class=\"line\"><span style=\"color:#FFAB70\">DATABASE_URL</span><span style=\"color:#F97583\">=</span><span style=\"color:#E1E4E8\">postgres://cuitty@localhost/cuitty</span></span>\n<span class=\"line\"><span style=\"color:#FFAB70\">SPICEDB_URL</span><span style=\"color:#F97583\">=</span><span style=\"color:#E1E4E8\">localhost:50051</span></span>\n<span class=\"line\"><span style=\"color:#FFAB70\">SPICEDB_TOKEN</span><span style=\"color:#F97583\">=</span><span style=\"color:#E1E4E8\">...</span></span>\n<span class=\"line\"><span style=\"color:#FFAB70\">BETTER_AUTH_SECRET</span><span style=\"color:#F97583\">=</span><span style=\"color:#E1E4E8\">...</span></span>\n<span class=\"line\"><span style=\"color:#FFAB70\">PORT</span><span style=\"color:#F97583\">=</span><span style=\"color:#E1E4E8\">7700</span></span>\n<span class=\"line\"><span style=\"color:#FFAB70\">DATA_DIR</span><span style=\"color:#F97583\">=</span><span style=\"color:#E1E4E8\">/var/lib/cuitty</span></span></code></pre>\n<h2 id=\"systemd-unit\">systemd unit</h2>\n<p><code>/etc/systemd/system/cuitty-portal.service</code>:</p>\n<pre class=\"astro-code github-dark\" style=\"background-color:#24292e;color:#e1e4e8; overflow-x: auto;\" tabindex=\"0\" data-language=\"ini\"><code><span class=\"line\"><span style=\"color:#B392F0\">[Unit]</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">Description</span><span style=\"color:#E1E4E8\">=Cuitty Portal</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">After</span><span style=\"color:#E1E4E8\">=network.target postgresql.service</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#B392F0\">[Service]</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">Type</span><span style=\"color:#E1E4E8\">=simple</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">EnvironmentFile</span><span style=\"color:#E1E4E8\">=/etc/cuitty/portal.env</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">ExecStart</span><span style=\"color:#E1E4E8\">=/usr/local/bin/cuitty-portal</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">Restart</span><span style=\"color:#E1E4E8\">=on-failure</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">User</span><span style=\"color:#E1E4E8\">=cuitty</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">Group</span><span style=\"color:#E1E4E8\">=cuitty</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">WorkingDirectory</span><span style=\"color:#E1E4E8\">=/var/lib/cuitty</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#B392F0\">[Install]</span></span>\n<span class=\"line\"><span style=\"color:#F97583\">WantedBy</span><span style=\"color:#E1E4E8\">=multi-user.target</span></span></code></pre>\n<pre class=\"astro-code github-dark\" style=\"background-color:#24292e;color:#e1e4e8; overflow-x: auto;\" tabindex=\"0\" data-language=\"bash\"><code><span class=\"line\"><span style=\"color:#B392F0\">systemctl</span><span style=\"color:#9ECBFF\"> daemon-reload</span></span>\n<span class=\"line\"><span style=\"color:#B392F0\">systemctl</span><span style=\"color:#9ECBFF\"> enable</span><span style=\"color:#79B8FF\"> --now</span><span style=\"color:#9ECBFF\"> cuitty-portal</span></span></code></pre>\n<h2 id=\"reverse-proxy\">Reverse proxy</h2>\n<p>Run Caddy or nginx in front of the portal for TLS termination. The portal expects to be reached over HTTPS in production for cookie-based auth to work correctly.</p>",
  "links_out": []
}