# Install the framework
> Install one runtime package, then build a small HTTP app. Add a database and other services when your feature needs them.
- Package: `@db3.ai/app`
- Canonical page: [https://db3.ai/docs/installation](https://db3.ai/docs/installation)
- Markdown: [https://db3.ai/docs/installation.md](https://db3.ai/docs/installation.md)
- Framework source of truth: `packages/app/README.md`
## Want a working app shell?
The `@db3.ai/create` preview generates a Vue/DOM Studio app with password login, private notes and optional AI summaries using your own server-side API key. Start there for a complete first feature. This page covers installing the runtime for a smaller HTTP app or script.
- [Create the notes and AI starter](https://db3.ai/docs/starter-app.md)
## Before you start
Use Node.js 24 or newer and npm for these walkthroughs. Start in a new directory, outside the framework repository. You do not need Scout, Vue, a database or cloud credentials for the first HTTP app.
The runtime package is `@db3.ai/app`. Its matching `@db3.ai/pure` dependency contains portable helpers. Fastify is optional: install it for this HTTP example, not for a script that only uses Storage.
## Publication status
The framework and creator are not published to npm yet. The intended released install command is shown below, but it will not work until the first release. Use matching package tarballs supplied by a maintainer for now.
### After publication only
```bash
npm install @db3.ai/app
```
## Install the current preview
Obtain the matching App and Pure tarballs from a framework maintainer. Replace both `/path/to/` values below with those files. Install them together because the unreleased App package depends on the matching Pure version.
Nothing in this command publishes your application. Marking it private also protects against accidentally running `npm publish` from the app directory.
### Current preview: run in a new directory
```bash
mkdir my-db3-app
cd my-db3-app
npm init -y
npm pkg set type=module
npm pkg set private=true --json
npm install /path/to/db3.ai-pure-0.1.0.tgz /path/to/db3.ai-app-0.1.0.tgz
```
## Add the development tools
`tsx` runs the copied TypeScript examples, TypeScript checks them, and Vitest runs your application tests. Fastify owns the HTTP listener; `App` owns framework services.
- [Create and run your first app](https://db3.ai/docs/create-app.md)
### Install HTTP and development dependencies
```bash
npm install fastify@^5
npm install --save-dev tsx@^4 typescript@^6 @types/node@^24 vitest@^4
```
## Configure SQL when a guide needs it
Auth, ActiveRecord, Media, database-backed Queue and Scheduler need MariaDB/MySQL. Their isolated labs require a dedicated local test account allowed to create and drop databases prefixed `db3_app_test_`. Do not use production credentials. Storage and the first HTTP app do not need SQL.
Save the configuration below as `.env` in your new app directory, replacing the user and password. Keep `.env` out of Git. `DATABASE_URL`, if set in your shell, takes precedence; unset it unless it deliberately points at your test server.
Each lab creates a unique database and removes it in `finally`. A forcibly killed process may leave a test database or temporary directory to inspect. The lab’s `Database.install()` is not your production migration workflow.
- [Native MariaDB setup](https://db3.ai/docs/starter-app.md#database)
- [Optional Docker setup](https://db3.ai/docs/starter-app.md#docker)
- [Test-account grants in the source-backed starter guide](https://db3.ai/docs/starter-app.md#testing)
### .env (test databases only)
```bash
DB_CONNECTION=mariadb
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=your_test_user
DB_PASSWORD=your_test_password
DB_DATABASE=db3_app_test
DB_TEST_DATABASE_PREFIX=db3_app_test
```
## When installation fails
An npm 404 for `@db3.ai/app` is expected before publication. For the preview, check that both tarball paths exist and their versions match. Do not substitute an unrelated npm package with a similar name.
If SQL reports connection refused, check its host and port. Access denied usually means credentials or grants; a socket-only account may not allow TCP login. Database creation needs additional test-account privileges beyond reading an existing database.
If port 3000 is occupied, choose another `PORT` when starting the HTTP example. None of the guides requires a global TypeScript or framework CLI installation.
## For framework maintainers
These commands are for a framework checkout only. They compile and pack the two public-shaped packages and verify a fresh consumer. They do not publish. Share the two resulting tarballs with preview users, who start at Install the current preview above.
### Framework repository only
```bash
npm run framework:package
npm pack ./dist/framework-packages/pure --pack-destination ./dist/framework-packages
npm pack ./dist/framework-packages/app --pack-destination ./dist/framework-packages
npm run framework:package:test
```
## What is working, and what comes next
The minimal HTTP guide below has a real HTTP test and uses installed package artifacts. The separate Notes + AI starter adds a generated Vue shell, authentication and migrations. Public npm installation remains a release gate, not an already available command.
- [Create an app and test it](https://db3.ai/docs/create-app.md)
- [Your standalone application layout](https://db3.ai/docs/create-app.md#layout)
## Related documentation
- [Create your first app](https://db3.ai/docs/create-app.md): Start an HTTP server, return a JSON response, reject invalid input and test it without opening a port.
- [App](https://db3.ai/docs/app.md): Create one application at boot. Configure its services, use request-local state and close the resources you own.
- [Auth](https://db3.ai/docs/auth.md): Give an account one or more login methods. Issue bearer sessions, reset passwords and revoke access without mixing identity with credentials.
## Guidance for AI tools
Use the documented public import `@db3.ai/app` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.