AkurAI-Build

Latest change 0cf28150faedd8c150474a4f16be4c9922c04f56 - feat: add Ponytail UI design system by Olafur Bui

{% extends "layouts/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 requires Rust 1.89 or newer (edition 2024) on the stable
        toolchain. 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>
        Health identifies the service, package version, and whole-second uptime.
        Readiness returns <code>{"message":"ok"}</code>; in native mode it also
        checks the open encrypted database. Both endpoints 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 %}