Astro Template Setup

Docker Compose Required

Crucial: All commands must be run through Docker Compose. Do not use local node, yarn, or astro CLIs directly.

Start the dev environment (runs on port 4321):

docker compose up -d

Run commands inside the container:

docker compose exec app <command>

Examples:

Add package: docker compose exec app yarn add <package>
Astro CLI: docker compose exec app yarn astro add <integration>

Project Structure

The source code is mounted at /usr/src/app. Host changes sync automatically.

src/pages/Your routing lives here. Edit index.astro to change this page.
src/components/Reusable Astro, React, or Vue components.
public/Static assets like images or fonts.

Adding a Database (Drizzle ORM)

1. Choose Your Database & Configure Docker

Configure your compose.yaml and .env.dist based on your database choice:

PostgreSQL (Default in Template)

The compose.yaml is already set up. Just ensure your .env.dist or .env contains:

POSTGRES_USER=app
POSTGRES_PASSWORD=!ChangeMe!
POSTGRES_DB=app
DATABASE_URL="postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db/${POSTGRES_DB}"

To use MySQL or SQLite instead, update your compose.yaml and .env.dist:

MySQL

# compose.yaml
services:
  db:
    image: mysql:8.0
    env_file:
      - .env.dist
    ports:
      - "3306:3306"

# .env.dist
MYSQL_USER=app
MYSQL_PASSWORD=!ChangeMe!
MYSQL_DATABASE=app
MYSQL_ROOT_PASSWORD=!RootChangeMe!
DATABASE_URL="mysql://${MYSQL_USER}:${MYSQL_PASSWORD}@db:3306/${MYSQL_DATABASE}"

SQLite

Remove the db service and add a named volume to app to preserve data:

# compose.yaml
services:
  app:
    # ... existing config ...
    volumes:
      - ./:/usr/src/app
      - sqlite_data:/usr/src/app/data

volumes:
  sqlite_data:

# .env.dist
DATABASE_URL="file:./data/local.db"

2. Install Dependencies (Inside Container)

Install Drizzle and the driver for your chosen database:

# Postgresyarn add pg
yarn add -D @types/pg

# MySQLyarn add mysql2

# SQLiteyarn add @libsql/client

Remember to run these prefixed with docker compose exec app

3. Initialize Configuration

Create a drizzle.config.ts at the project root matching your dialect:

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dialect: "postgresql", // or "mysql", "sqlite"
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Then define your schema in src/db/schema.ts.

✨ Magic Entrypoint: The Docker container automatically detects when you install drizzle-kit and create drizzle.config.ts. Every time the container starts, it will automatically run yarn drizzle-kit push (or migrate if you have a drizzle folder). You don't need to run sync commands manually!

Drizzle ORM Docs →

Schema definition, querying, and migrations.

Astro Documentation

Routing & Pages →

Dynamic routes, middleware, and page structure.

Astro Components →

The core building block of Astro projects.

UI Frameworks →

Using React, Vue, Svelte, and others.

Styling & Tailwind →

Adding styles and configuring Tailwind CSS.

Content Collections →

Manage Markdown/MDX with type safety.