Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ItsJhonAlex/Ecommerce/llms.txt

Use this file to discover all available pages before exploring further.

This quickstart walks you through cloning the repository, configuring your environment, spinning up the PostgreSQL database via Docker, running migrations, seeding an admin user, and launching all three apps together. By the end you will have the backend API, admin dashboard, and public storefront running locally and ready for development.

​
Prerequisites

Before you begin, make sure the following tools are installed on your machine:

​
Setup

1

Clone the repository

git clone https://github.com/ItsJhonAlex/Ecommerce.git && cd Ecommerce
2

Install dependencies

Install all workspace dependencies from the monorepo root in a single command:
bun install
Bun resolves workspaces declared under apps/* and packages/* and hoists shared dependencies automatically.
3

Configure environment variables

Copy the example environment file and edit the values to match your local setup:
cp .env.example .env
The .env file at the monorepo root is shared by all apps via --env-file=../../.env:
VariableDefaultPurpose
POSTGRES_USERavanzarPostgreSQL username
POSTGRES_PASSWORDchangemePostgreSQL password — change this
POSTGRES_DBavanzarDatabase name
POSTGRES_HOST_PORT5433Host port mapped to the container’s 5432
DATABASE_URLpostgres://avanzar:changeme@localhost:5433/avanzarFull connection string used by Drizzle
PORT3000Hono backend listen port
BETTER_AUTH_SECRETchangemeSecret key for session signing — generate a strong value
BETTER_AUTH_URLhttp://localhost:3000Public base URL of the backend, used by Better Auth
Generate a strong BETTER_AUTH_SECRET with:
bun -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
4

Start the PostgreSQL database

Launch the PostgreSQL 17 container in the background:
bun run db:up
This runs docker compose up -d. The container is named avanzar_postgres and exposes the database on the host port defined by POSTGRES_HOST_PORT (default 5433). A Docker volume named avanzar_pgdata persists data across restarts.
5

Run database migrations

Apply all Drizzle migrations to the running database:
bun run db:migrate
This delegates to drizzle-kit migrate inside the @avanzar/db package, creating all tables, enums, and constraints defined in the schema.
6

Create an admin user

Seed the initial admin account using the bootstrap script. Run it from the monorepo root via the workspace filter:
bun run --filter '@avanzar/backend' seed:admin
Alternatively, run it directly from the backend directory:
cd apps/backend && bun run seed:admin
This executes apps/backend/src/scripts/create-admin.ts via bun run --env-file=../../.env, creates a user through Better Auth, and promotes it to the admin role. Follow the interactive prompts in your terminal to set the name, email, and password. The script is idempotent — if the email already exists it will only update the role.
7

Start all apps

Start the backend, storefront, and admin dashboard in parallel from the monorepo root:
bun run dev
Hot reload is enabled for the backend via the --hot flag (bun run --hot src/index.ts). Changes to backend source files are applied instantly without restarting the process.

​
Running Services

Once bun run dev is running, the following services are available:
ServiceURL
Backend APIhttp://localhost:3000
API Docs (Swagger UI)http://localhost:3000/api/v1/docs
Storefronthttp://localhost:4321
Admin Dashboardhttp://localhost:5174

​
Running Individual Apps

To start only one app at a time, use the targeted dev commands from the monorepo root: 
# Backend only
bun run dev:backend

# Astro storefront only
bun run dev:storefront

# React admin dashboard only
bun run dev:admin

​
Database Commands

All database operations are available as root-level scripts that delegate to the @avanzar/db package:
CommandDescription
bun run db:generateGenerate a new Drizzle migration from schema changes
bun run db:migrateApply pending migrations to the database
bun run db:pushPush schema changes directly without a migration file
bun run db:studioOpen Drizzle Studio in the browser for visual DB inspection
bun run db:upStart the PostgreSQL Docker container (docker compose up -d)
bun run db:downStop and remove the PostgreSQL Docker container

Build docs developers (and LLMs) love

Get started for freeTalk to us