Development environment and example application

Companions:

• Configuration — the server, admin, schema, and public files you will edit after the reference application is running.
• CLI — the alternative path for installing Byline into an existing TanStack Start application.
• Testing — the database setup, suite boundaries, and commands used to verify repository changes.

By the end of this guide you will have the Byline reference application (apps/webapp) running locally against a seeded PostgreSQL database, viewable at http://localhost:5173/. It is the quickest way to see a working Byline installation.

Prerequisites: Node >=20.9.0, pnpm, and Docker (for the bundled PostgreSQL container). If you'd rather add Byline to an existing TanStack Start app than run this repo, use the CLI instead.

1. Clone and install dependencies

# git clone this repo
git clone [email protected]:Byline-CMS/bylinecms.dev.git
cd bylinecms.dev
# install deps
pnpm install
# build once so that all workspace packages and apps have their deps
pnpm build

2. Set up your database

The repository's reference application is configured for PostgreSQL. Byline also supports MySQL through the CLI, but this guide follows the checked-in apps/webapp configuration and the docker-compose.yml in the root postgres directory. The default root password is set to test in docker-compose.yml.

2.1. Create the data subdirectory and start Postgres

# From the root of the project
cd postgres
mkdir data
# If you want to run docker detached, run './postgres.sh up -d'
./postgres.sh up

# And then 'down' if you want to remove the Docker container and network
# configuration when you're done.
./postgres.sh down

2.2. Initialize the database and schema

Initialize the PostgreSQL adapter used by the reference application:

# From the repository root, copy the adapter environment template.
cp packages/db-postgres/.env.example packages/db-postgres/.env

# Again, the default database root password is 'test'
# (assuming you're using our docker-compose.yml file).
pnpm db:init

# You can optionally run pnpm drizzle:generate, although since
# this is a development repo - migrations have already been generated
# and committed.
# pnpm drizzle:generate
pnpm drizzle:migrate

2.3. Configure the webapp, and optionally seed documents

# Seed the database with a single super-admin user — and optionally,
# categories and documents.
# From apps/webapp. The seed scripts live in
# apps/webapp/byline/seeds, orchestrated by apps/webapp/byline/seed.ts
cd apps/webapp

# .env configuration
cp .env.local.example .env.local

# generate JWT session key
openssl rand -base64 48
# Paste the output into .env.local as:
# BYLINE_JWT_SECRET=

# Set the seed superadmin username email address and password
# BYLINE_SUPERADMIN_EMAIL=admin@byline.local
# BYLINE_SUPERADMIN_PASSWORD=change-me

pnpm tsx --env-file=.env.local byline/seed.ts

3. Start dev mode

Again, from the root of the project, start the dev environment.

pnpm dev

If you've built the project (above) and have Postgres up and running, you should be able to view the app on http://localhost:5173/ .

The application is now ready for local development.

Next

• Sign in with the super-admin credentials you set in .env.local, then explore the seeded collections in the admin.
• Collections is the working reference for defining your own content types.
• Architecture maps the design decisions behind the storage and versioning model.