mirror of
https://github.com/trailbaseio/trailbase
synced 2026-04-21 13:37:44 +00:00
Overhaul getting started guide: steer folks more towards an install rather than docker.
This commit is contained in:
Sebastian Jeltsch
parent
78545307b3
commit
e091f8212d
20 changed files with 131 additions and 137 deletions
|
|
@ -57,8 +57,8 @@ export default defineConfig({
|
|||
label: "Getting Started",
|
||||
items: [
|
||||
{
|
||||
label: "Starting Up",
|
||||
slug: "getting-started/starting-up",
|
||||
label: "Install & Run",
|
||||
slug: "getting-started/install",
|
||||
},
|
||||
{
|
||||
label: "Tutorials",
|
||||
|
|
@ -72,7 +72,7 @@ export default defineConfig({
|
|||
slug: "getting-started/first-cli-app",
|
||||
},
|
||||
{
|
||||
label: "Realtime Sync & SSR",
|
||||
label: "Realtime-sync & SSR",
|
||||
slug: "getting-started/first-realtime-app",
|
||||
},
|
||||
],
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ description: Comparing TrailBase & PocketBase.
|
|||
---
|
||||
|
||||
import { Aside } from "@astrojs/starlight/components";
|
||||
import GettingTrailBase from "../getting-started/_getting_trailbase.md";
|
||||
import GettingTrailBase from "../getting-started/_getting_trailbase.mdx";
|
||||
|
||||
Firstly, PocketBase is amazing! It paved the way for single-executable
|
||||
application bases, is incredibly easy-to-use, and a polished
|
||||
|
|
@ -128,11 +128,7 @@ better off with PocketBase.
|
|||
Otherwise it may be worth giving TrailBase a closer look, especially when
|
||||
flexibility and performance matter.
|
||||
|
||||
<Aside type="note" title="Getting TrailBase">
|
||||
<GettingTrailBase />
|
||||
</Aside>
|
||||
|
||||
<div class="h-[30px]" />
|
||||
<GettingTrailBase />
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -33,8 +33,6 @@ Ultimately, the biggest difference is that SupaBase is a polished product with
|
|||
a lot of mileage under its belt. Our simpler architecture will hopefully let us
|
||||
get there but for now SupaBase is our north star.
|
||||
|
||||
<div class="h-[30px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -529,8 +529,6 @@ addition to your toolbox.
|
|||
|
||||
*/}
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -126,8 +126,6 @@ However, the auth token will remain valid until it expires. In other words, to
|
|||
ensure that users don't appear as logged in anymore, any auth token you may
|
||||
have persisted should be dropped.
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -91,8 +91,6 @@ modules are:
|
|||
* extensions and modules can also be used by services accessing the
|
||||
underlying SQLite databases.
|
||||
|
||||
<div class="h-[30px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -254,8 +254,6 @@ the other stable.
|
|||
Alternatively, custom JS/TS handlers can provide a more free-form approach to
|
||||
push joining edges and other responsibilities to the server.
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -71,10 +71,6 @@ TrailBase also supports generating type-safe bindings for columns containing
|
|||
JSON data and enforcing a specific JSON schema, see
|
||||
[here](/documentation/apis/record_apis/#custom-json-schemas).
|
||||
|
||||
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -1,15 +0,0 @@
|
|||
You can download the latest pre-built `trail` binary for Mac, Windows and Linux
|
||||
from [GitHub](https://github.com/trailbaseio/trailbase/releases/).
|
||||
|
||||
Alternatively, you can use a Docker image from DockerHub:
|
||||
|
||||
```bash
|
||||
$ alias trail="docker run \
|
||||
--network host \
|
||||
--mount type=bind,source=$PWD/traildepot,target=/app/traildepot \
|
||||
trailbase/trailbase /app/trail"
|
||||
$ mkdir traildepot # pre-create mount point for Docker
|
||||
$ trail run
|
||||
```
|
||||
|
||||
or compile from [source](https://github.com/trailbaseio/trailbase).
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
import { Aside } from '@astrojs/starlight/components';
|
||||
import InstallOneLiners from "./_install_oneliners.mdx";
|
||||
|
||||
<Aside type="note" title="Getting Started">
|
||||
To install TrailBase check out the [guide](/getting-started/install/) or
|
||||
simply use one of the following commands:
|
||||
|
||||
<InstallOneLiners />
|
||||
</Aside>
|
||||
28
docs/src/content/docs/getting-started/_install_oneliners.mdx
Normal file
28
docs/src/content/docs/getting-started/_install_oneliners.mdx
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
import { Code, Tabs, TabItem } from '@astrojs/starlight/components';
|
||||
|
||||
export const installMacLinux = `curl -sSL https://raw.githubusercontent.com/trailbaseio/trailbase/main/install.sh | bash`;
|
||||
export const installWindows = `iwr https://raw.githubusercontent.com/trailbaseio/trailbase/main/install.sh | iex`;
|
||||
export const installDocker= `
|
||||
# Docker is used here merely as an easy, portable way to install TrailBase.
|
||||
# To make this persistent, you'll have to add the alias to your shell's rc.
|
||||
alias trail='
|
||||
mkdir traildepot && \\
|
||||
docker run \\
|
||||
--network host \\
|
||||
--mount type=bind,source="$PWD"/traildepot,target=/app/traildepot \\
|
||||
trailbase/trailbase /app/trail'
|
||||
`;
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="MacOS/Linux">
|
||||
<Code lang="sh" code={installMacLinux} frame={false} />
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Windows">
|
||||
<Code lang="sh" code={installWindows} frame={false} />
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Docker">
|
||||
<Code lang="sh" code={installDocker} frame={false} />
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -14,11 +14,9 @@ simply trying out TrailBase with an existing SQLite-based data-focused
|
|||
project, we will also offer an alternative path to bootstrapping the database
|
||||
using the vanilla `sqlite3` CLI.
|
||||
|
||||
import GettingTrailBase from "./_getting_trailbase.md";
|
||||
import GettingTrailBase from "./_getting_trailbase.mdx";
|
||||
|
||||
<Aside type="note" title="Getting TrailBase">
|
||||
<GettingTrailBase/>
|
||||
</Aside>
|
||||
<GettingTrailBase/>
|
||||
|
||||
## Create the Schema
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,6 @@ title: >
|
|||
---
|
||||
|
||||
import { Code } from "@astrojs/starlight/components";
|
||||
import { Aside } from "@astrojs/starlight/components";
|
||||
|
||||
This article is a short introduction to some of TrailBase more advanced
|
||||
features, specifically server-side rendering with a popular JS framework
|
||||
|
|
@ -31,11 +30,9 @@ $ git clone https://github.com/trailbaseio/trailbase.git
|
|||
$ cd trailbase/examples/collab-clicker-ssr
|
||||
```
|
||||
|
||||
import GettingTrailBase from "./_getting_trailbase.md";
|
||||
import GettingTrailBase from "./_getting_trailbase.mdx";
|
||||
|
||||
<Aside type="note" title="Getting TrailBase">
|
||||
<GettingTrailBase/>
|
||||
</Aside>
|
||||
<GettingTrailBase/>
|
||||
|
||||
## Creating an SSR Template Project
|
||||
|
||||
|
|
@ -419,8 +416,6 @@ Beyond the basic example above, the repository contains a more involved examples
|
|||
Any questions or suggestions? Reach out on GitHub and help us improve the docs.
|
||||
Thanks!
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
----
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -28,11 +28,9 @@ $ git clone https://github.com/trailbaseio/trailbase.git
|
|||
$ cd trailbase/examples/coffee-vector-search
|
||||
```
|
||||
|
||||
import GettingTrailBase from "./_getting_trailbase.md";
|
||||
import GettingTrailBase from "./_getting_trailbase.mdx";
|
||||
|
||||
<Aside type="note" title="Getting TrailBase">
|
||||
<GettingTrailBase/>
|
||||
</Aside>
|
||||
<GettingTrailBase/>
|
||||
|
||||
## Importing Data
|
||||
|
||||
|
|
@ -199,7 +197,7 @@ $ docker build -t coffee . && docker run -p 4000:4000 coffee
|
|||
```
|
||||
|
||||
will speed-run this entire tutorial by building and starting the app listening
|
||||
at [http://localhost:4000/](http://localhost:4000/).
|
||||
on [http://localhost:4000/](http://localhost:4000/).
|
||||
|
||||
That's it. We hope this was a fun little intro to some of TrailBase's features.
|
||||
There's more we haven't touched on: CRUD APIs, auth, admin dash, file uploads,
|
||||
|
|
@ -222,8 +220,6 @@ Beyond the basic example above, the repository contains a more involved examples
|
|||
Any questions or suggestions? Reach out on GitHub and help us improve the docs.
|
||||
Thanks!
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
----
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@ title: Our Goals
|
|||
---
|
||||
|
||||
TrailBase's goal is to help address common needs with standard solutions and
|
||||
best-practices, while being blazingly fast, w/o lock-in, or getting in your
|
||||
way.
|
||||
best-practices, while being simple, fast, avoiding lock-in and not getting in
|
||||
your way.
|
||||
|
||||
It's enough to wrangle your evolving product needs, you shouldn't also have to
|
||||
fight your platform or be held hostage.
|
||||
|
|
@ -56,8 +56,6 @@ TrailBase attempts to give you the best of both worlds:
|
|||
In the end, all paths lead to SQL as the only truly cross-platform,
|
||||
cross-database, cross-language solution[^2] 😉.
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
79
docs/src/content/docs/getting-started/install.mdx
Normal file
79
docs/src/content/docs/getting-started/install.mdx
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
---
|
||||
title: Install & Run
|
||||
description: Quick installation and startup guide
|
||||
---
|
||||
|
||||
import { Aside, Code } from '@astrojs/starlight/components';
|
||||
|
||||
|
||||
Welcome! In this *Getting Started* guide, we'll first see how to install
|
||||
TrailBase, followed by tutorials on building our first small applications.
|
||||
|
||||
TrailBase is a **single static executable** and therefore very easy to install.
|
||||
It's as simple as downloading the latest
|
||||
[release](https://github.com/trailbaseio/trailbase/releases) for your
|
||||
system and running it. If you prefer building your own binary, check out our
|
||||
[GitHub](https://github.com/trailbaseio/trailbase) page.
|
||||
|
||||
If you want to get started even quicker, you can simply run one of the
|
||||
following commands:
|
||||
|
||||
import InstallOneLiners from "./_install_oneliners.mdx";
|
||||
|
||||
<InstallOneLiners />
|
||||
|
||||
Once installed, you can run
|
||||
|
||||
<Code lang="sh" code={"trail help"} frame={false} />
|
||||
|
||||
to check that the executable is properly installed and see all available
|
||||
command line options.
|
||||
|
||||
|
||||
## Starting the Server & Admin Dashboard
|
||||
|
||||
After successfully installing TrailBase above, you can run
|
||||
|
||||
<Code lang="sh" code={"trail run"} frame={false} />
|
||||
|
||||
to bring up the server on `localhost:4000`.
|
||||
|
||||
On first start, a `./traildepot` folder will be created. It contains
|
||||
configuration, databases, secrets and a few more things.
|
||||
Moreover, an admin user will be created with their credentials printed to your
|
||||
terminal.
|
||||
Watch out for something like:
|
||||
|
||||
```
|
||||
Created new admin user:
|
||||
email: 'admin@localhost'
|
||||
password: '<random>'
|
||||
```
|
||||
|
||||
Optionally, you can change the credentials to something more fitting:
|
||||
|
||||
<Code lang="sh" code={`
|
||||
trail user change-password admin@localhost mypassword
|
||||
trail user change-email admin@localhost me@mydomain.org
|
||||
`} frame={false} />
|
||||
|
||||
|
||||
<Aside type="tip" title="Starting Over">
|
||||
Don't worry about breaking anything, you can always delete `traildepot` and start from scratch.
|
||||
</Aside>
|
||||
|
||||
Armed with your new credentials, open http://localhost:4000/_/admin/ in your
|
||||
browser and log in.
|
||||
|
||||
We encourage you to take a few minutes, click around, and maybe create a table
|
||||
or two.
|
||||
Note that when creating, altering, or deleting tables, indexes or views a
|
||||
schema migration file will be created in `traildepot/migrations`. This allows
|
||||
TrailBase to enforce consistent schemas across multiple database instances for
|
||||
dev, test, prod, ... .
|
||||
|
||||
If you like what you see and want to get your hands dirty, consider checking
|
||||
out some of the tutorials.
|
||||
Lastly, if you have any issues or feedback, don't hesitate and reach out either
|
||||
on [GitHub](https://github.com/trailbaseio/trailbase) or via
|
||||
*contact@trailbase.io*.
|
||||
|
|
@ -1,72 +0,0 @@
|
|||
---
|
||||
title: Starting Up
|
||||
description: A guide in my new Starlight docs site.
|
||||
---
|
||||
|
||||
import { Aside } from "@astrojs/starlight/components";
|
||||
import { Icon } from 'astro-icon/components'
|
||||
|
||||
In getting-started guide we'll bring up a local TrailBase instance, explore the
|
||||
admin dashboard, and implement our first, small application.
|
||||
|
||||
## Starting TrailBase
|
||||
|
||||
The quickest way to get TrailBase up and running is to use docker:
|
||||
|
||||
```bash
|
||||
$ mkdir traildepot
|
||||
$ docker run --network host --mount type=bind,source=$PWD/traildepot,target=/app/traildepot trailbase/trailbase
|
||||
```
|
||||
|
||||
On first start, TrailBase will generate a `traildepot` folder in your working
|
||||
directory containing its configuration, the database, secrets and a few more
|
||||
things.
|
||||
It will also generate a new admin user for you. The credentials will be printed
|
||||
on the command line as follows:
|
||||
|
||||
```
|
||||
Created new admin user:
|
||||
email: 'admin@localhost'
|
||||
password: '<random>'
|
||||
```
|
||||
|
||||
If you like, feel free to change the Email or password later in the dashboard.
|
||||
Independently, if you ever forget your password, you can reset it using the
|
||||
`trail user reset-password admin@localhost <new_pw>` command.
|
||||
|
||||
## The Admin Dashboard
|
||||
|
||||
After successfully starting TrailBase, we can check out the admin dashboard under
|
||||
[http://localhost:4000/\_/admin/](http://localhost:4000/_/admin/).
|
||||
After logging in with the admin credentials from the terminal, there's a couple
|
||||
of pages to explore.
|
||||
|
||||
* First and maybe most importantly: the data browser
|
||||
(<span class="not-content inline align-middle"><Icon name="tabler:database" /></span>)
|
||||
that let's you explore and alter both the data as well as table schemas. It
|
||||
provides access to _tables_, _views_, _virtual tables_, _indexes_, _triggers_
|
||||
as well as your TrailBase API settings.
|
||||
* The simple SQL editor
|
||||
(<span class="not-content inline align-middle"><Icon name="tabler:edit" /></span>)
|
||||
lets you run arbitrary queries against the database and take full control.
|
||||
It also lets you access SQLite features which aren't (yet) exposed via the
|
||||
dashboard.
|
||||
* The accounts page
|
||||
(<span class="not-content inline align-middle"><Icon name="tabler:users" /></span>)
|
||||
lets you manage your registered users.
|
||||
* The logs page
|
||||
(<span class="not-content inline align-middle"><Icon name="tabler:timeline" /></span>)
|
||||
lets you see what's going on. At this early stage you're probably just seeing
|
||||
your own interactions with the admin dashboard.
|
||||
* The settings page
|
||||
(<span class="not-content inline align-middle"><Icon name="tabler:settings" /></span>)
|
||||
lets you configure instance-wide settings.
|
||||
Alternatively, you can also directly edit TrailBase's config file, however, unlike
|
||||
the UI you'll need to restart the server to apply the changes.
|
||||
TrailBase uses protobuf for its configuration. The schema can be
|
||||
found [here](https://github.com/trailbaseio/trailbase/blob/main/trailbase-core/proto/config.proto).
|
||||
|
||||
We encourage you to take a minute, click around, and maybe create a few tables.
|
||||
Don't worry about breaking anything. Also note that when creating, altering, or
|
||||
deleting a table a schema migration file will be created in
|
||||
`traildepot/migrations`.
|
||||
|
|
@ -20,7 +20,7 @@ hero:
|
|||
file: ../../assets/logo_512.webp
|
||||
actions:
|
||||
- text: Documentation
|
||||
link: /getting-started/starting-up
|
||||
link: /getting-started/install
|
||||
icon: right-arrow
|
||||
- text: FAQ
|
||||
link: /reference/faq/
|
||||
|
|
|
|||
|
|
@ -285,8 +285,6 @@ In any case, we hope this was at least somewhat insightful. Let us know if you s
|
|||
anything that can or should be improved.
|
||||
The benchmarks are available on [GitHub](https://github.com/trailbaseio/trailbase-benchmark).
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
|
|
@ -148,8 +148,6 @@ sqlite3 main.db < import.sql
|
|||
|
||||
Also check out the [getting started](/getting-started/first-cli-app) guide.
|
||||
|
||||
<div class="h-[50px]" />
|
||||
|
||||
---
|
||||
|
||||
[^1]:
|
||||
|
|
|
|||
Loading…
Reference in a new issue