Astro + PostgreSQL

Key Features

• Island architecture with zero JavaScript by default, only hydrating interactive components that need client-side behavior
• Multi-framework component support allowing React, Vue, Svelte, and other UI frameworks within the same Astro project
• Content Collections with TypeScript-safe frontmatter validation for structured content management
• Server-side rendering with Astro adapters while maintaining static-first philosophy for optimal performance
• PostgreSQL's ACID compliance ensuring data integrity for user-generated content and transactional operations
• Advanced PostgreSQL JSON/JSONB support for flexible content schemas alongside traditional relational data
• Built-in Astro dev server with hot module replacement and fast refresh during development
• PostgreSQL full-text search capabilities with ranking and highlighting for content discovery

Common Use Cases

• 1Documentation sites with dynamic search, user authentication, and contribution tracking stored in PostgreSQL
• 2Content marketing websites with blog posts, case studies, and lead capture forms backed by relational data
• 3E-commerce product catalogs using Astro's static generation for product pages with PostgreSQL inventory management
• 4SaaS marketing sites with dynamic pricing tables, feature comparisons, and customer testimonials from database
• 5Portfolio websites with project galleries, contact forms, and analytics tracking using PostgreSQL storage
• 6News and magazine sites with article management, author profiles, and comment systems requiring database relationships
• 7Corporate websites with dynamic team directories, press releases, and investor relations data from PostgreSQL

Prerequisites

• Docker and Docker Compose installed with at least 1.5GB available RAM for PostgreSQL operation
• Node.js knowledge for Astro development and understanding of static site generation concepts
• Basic SQL skills for PostgreSQL database design, queries, and data modeling
• Port 4321 available for Astro development server and port 5432 free for PostgreSQL connections
• Understanding of environment variables for database connection configuration and secrets management
• Familiarity with at least one UI framework (React, Vue, Svelte) if building interactive components

docker-compose.yml

1services: 
2  astro: 
3    build: .
4    container_name: astro
5    environment: 
6      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
7    ports: 
8      - "4321:4321"
9    depends_on: 
10      - postgres
11    networks: 
12      - astro-network
13
14  postgres: 
15    image: postgres:16-alpine
16    environment: 
17      POSTGRES_DB: ${DB_NAME}
18      POSTGRES_USER: ${DB_USER}
19      POSTGRES_PASSWORD: ${DB_PASSWORD}
20    volumes: 
21      - postgres_data:/var/lib/postgresql/data
22    networks: 
23      - astro-network
24
25volumes: 
26  postgres_data: 
27
28networks: 
29  astro-network: 
30    driver: bridge

.env Template

1DB_NAME=astro
2DB_USER=astro
3DB_PASSWORD=changeme

Usage Notes

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

astro:
  build: .
  container_name: astro
  environment:
    DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
  ports:
    - "4321:4321"
  depends_on:
    - postgres
  networks:
    - astro-network

postgres:
  image: postgres:16-alpine
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - astro-network

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  astro:
5    build: .
6    container_name: astro
7    environment:
8      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
9    ports:
10      - "4321:4321"
11    depends_on:
12      - postgres
13    networks:
14      - astro-network
15
16  postgres:
17    image: postgres:16-alpine
18    environment:
19      POSTGRES_DB: ${DB_NAME}
20      POSTGRES_USER: ${DB_USER}
21      POSTGRES_PASSWORD: ${DB_PASSWORD}
22    volumes:
23      - postgres_data:/var/lib/postgresql/data
24    networks:
25      - astro-network
26
27volumes:
28  postgres_data:
29
30networks:
31  astro-network:
32    driver: bridge
33EOF
34
35# 2. Create the .env file
36cat > .env << 'EOF'
37DB_NAME=astro
38DB_USER=astro
39DB_PASSWORD=changeme
40EOF
41
42# 3. Start the services
43docker compose up -d
44
45# 4. View logs
46docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/astro-postgres/run | bash

Troubleshooting