AkurAI-Build

Latest change 1c2159692a31765cd66ed709791ba11468054873 - Initial commit: bunfork v0.1.0 source tree by Olafur Bui

{% extends "docs.html" %}
{% block title %}Getting started · Bunfork docs{% endblock %}
{% block description %}Build Bunfork, generate separate database and API secrets, migrate encrypted SQLite, and start the native server on port 3100.{% endblock %}
{% block breadcrumb %}Getting started{% endblock %}
{% block docs_title %}Getting started{% endblock %}
{% block docs_summary %}Go from a clean checkout to the native server in five commands. Static exports have a shorter, secret-free path below.{% endblock %}
{% block docs_content %}
<section class="doc-section" aria-labelledby="native-setup">
  <h2 id="native-setup">Run the native application</h2>
  <ol class="steps">
    <li>
      <h3>Build the pinned source</h3>
      <pre><code>cargo build --release --locked</code></pre>
      <p>Bunfork uses the stable Rust toolchain and edition 2024. SQLCipher and OpenSSL are bundled by the database dependency.</p>
    </li>
    <li>
      <h3>Create two different secrets</h3>
      <pre><code>./target/release/bunfork keygen
./target/release/bunfork keygen --out .bunfork.token</code></pre>
      <p>Each file contains a private 256-bit secret. The decoded database key and API token must differ; case-only hex variations are rejected as equal.</p>
    </li>
    <li>
      <h3>Apply the embedded migration</h3>
      <pre><code>./target/release/bunfork migrate</code></pre>
      <p>The database is created at <code>data/bunfork.db</code> by default. Migrations run transactionally, then the exact schema and ledger are validated.</p>
    </li>
    <li>
      <h3>Start development mode</h3>
      <pre><code>./target/release/bunfork dev</code></pre>
      <p>The default listener is <code>0.0.0.0:3100</code>. Native templates and routes are rescanned per request; this is server reload, not browser HMR.</p>
    </li>
    <li>
      <h3>Probe readiness</h3>
      <pre><code>curl --fail http://localhost:3100/api/health
curl --fail http://localhost:3100/_bunfork/ready</code></pre>
      <p>Both endpoints return <code>{"message":"ok"}</code> and are intentionally public.</p>
    </li>
  </ol>
</section>

<aside class="doc-callout warning" aria-labelledby="lan-warning">
  <h2 id="lan-warning">The default is LAN-visible</h2>
  <p><code>0.0.0.0:3100</code> accepts traffic on every interface. Keep it behind a host firewall on trusted networks. Before internet exposure, put a trusted TLS reverse proxy in front and set <code>BUNFORK_PUBLIC_ORIGIN</code> to the external HTTPS origin.</p>
</aside>

<section class="doc-section" aria-labelledby="static-setup">
  <h2 id="static-setup">Serve a static export without secrets</h2>
  <p>Static mode never opens SQLCipher and does not read the database key, API token, tenant, or model. First build the browser artifact with its own toolchain, then:</p>
  <pre><code>./target/release/bunfork admit \
  --artifact frontend/dist \
  --manifest bunfork-static.json \
  --mode spa \
  --fallback index.html \
  --trailing-slash ignore

./target/release/bunfork doctor \
  --static frontend/dist \
  --manifest bunfork-static.json

./target/release/bunfork serve \
  --static frontend/dist \
  --manifest bunfork-static.json</code></pre>
  <p>Use the SPA settings only when the client router requires an explicit <code>index.html</code> fallback. Prerendered multi-page exports should use MPA mode.</p>
</section>

<section class="doc-section" aria-labelledby="paths-and-env">
  <h2 id="paths-and-env">Override state explicitly</h2>
  <pre><code>./target/release/bunfork \
  --database "$HOME/.local/share/bunfork/bunfork.db" \
  --key-file "$HOME/.config/bunfork/db.key" \
  --tenant acme \
  --model notes \
  serve --token-file "$HOME/.config/bunfork/api.token"</code></pre>
  <p>Global data options must precede the command. Their environment equivalents are <code>BUNFORK_DB</code>, <code>BUNFORK_KEY_FILE</code>, <code>BUNFORK_TENANT</code>, and <code>BUNFORK_MODEL</code>.</p>
</section>

<nav class="docs-pagination" aria-label="Documentation pagination">
  <a href="/docs"><small>Previous</small><span aria-hidden="true">←</span> Overview</a>
  <a href="/docs/frameworks"><small>Next</small>Framework exports <span aria-hidden="true">→</span></a>
</nav>
{% endblock %}