Skip to main content

​
Quickstart

Get Aya up and running on your local machine in just a few minutes using Docker Compose.
Prerequisites: Make sure you have Docker and Git installed. OrbStack is recommended for Mac users.

​
Quick Setup

1

Clone the repository

git clone [email protected]:eser/aya.is.git
cd aya.is
2

Create environment configuration

The backend requires at minimum the AUTH__JWT_SECRET environment variable:
cat > apps/services/.env.local << EOF
AUTH__JWT_SECRET=your-secret-key-here
EOF
Replace your-secret-key-here with any random string. For production, use a cryptographically secure random value.
3

Start all services

make up
This command will:
  • Build Docker images for frontend and backend
  • Start PostgreSQL database
  • Run database migrations
  • Start the backend API server
  • Start the frontend development server
4

Access the application

Once the containers are running, access:

Frontend

http://localhost:3000

Backend API

http://localhost:8080
The frontend will automatically proxy API requests to the backend, so you typically only need to interact with localhost:3000.

​
What’s Running?

After make up, you have three services:

​
PostgreSQL Database

  • Port: 5432
  • Database: postgres
  • User: postgres
  • Password: s3cr3t
  • Persistent storage: Docker volume postgres-data

​
Backend (Go Services)

  • Port: 8080
  • Runtime: Go 1.25 with Air for hot reload
  • Config: apps/services/config.json + environment variables
  • Features:
    • REST API endpoints
    • JWT-based authentication
    • Database migrations (auto-applied on startup)
    • Optional Telegram bot integration

​
Frontend (Deno + TanStack Start)

  • Port: 3000
  • Runtime: Deno with Vite
  • Features:
    • Server-side rendering (SSR)
    • Hot module replacement (HMR)
    • File-based routing
    • TanStack Query for data fetching

​
Useful Commands

Once you have Aya running, use these Make commands: 
make logs

# Or for specific service:
make logs services
make logs webclient

​
Verify Installation

Test that everything is working:
1

Check backend health

curl http://localhost:8080/health
Expected response:
{"status":"ok"}
2

Visit the frontend

Open http://localhost:3000/en in your browser.You should see the Aya homepage with:
  • Navigation header
  • Locale selector (13 languages)
  • Featured content
3

Check Docker containers

docker compose ps
All three services should show as Up:
NAME                          STATUS
aya-is-development-postgres-1    Up (healthy)
aya-is-development-services-1    Up
aya-is-development-webclient-1   Up

​
Optional: Telegram Bot Integration

To enable the Telegram bot for notifications and interactions:
1

Create a bot with BotFather

  1. Open Telegram and message @BotFather
  2. Send /newbot and follow the prompts
  3. Copy the bot token provided
2

Add environment variables

Edit apps/services/.env.local and add:
# Telegram Bot Configuration
TELEGRAM__ENABLED=true
TELEGRAM__BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM__BOT_USERNAME=your_bot_username
TELEGRAM__USE_POLLING=true
WORKERS__TELEGRAM_BOT__ENABLED=true
In development, use polling mode (USE_POLLING=true) which doesn’t require a public URL.
3

Restart services

make restart services
Check logs to verify the bot started:
make logs services | grep telegram

​
Development Workflow

​
Hot Reload

Both frontend and backend support hot reload:
  • Frontend: Vite HMR updates instantly on file changes
  • Backend: Air watches Go files and rebuilds/restarts automatically

​
Watch Mode

For the fastest feedback loop, use watch mode: 
make watch
This enables Docker Compose’s watch feature:
  • Frontend: syncs src/ changes without rebuild
  • Backend: syncs pkg/ and triggers restart
  • Faster than rebuilding containers

​
Accessing the Backend CLI

The services container includes a Node.js-based CLI for database operations: 
make cli
Once inside, you can use the backend object: 
// Get a profile
await backend.getProfile("en", "eser");

// List stories
await backend.getStories("en");

​
Troubleshooting

If you see errors like “bind: address already in use”:
# Check what's using the port
lsof -i :3000
lsof -i :8080
lsof -i :5432

# Kill the process or change ports in compose.yml
If the backend can’t connect to PostgreSQL:
# Check if postgres is healthy
docker compose ps postgres

# View postgres logs
docker compose logs postgres

# Restart postgres
docker compose restart postgres
If you see Deno/Vite errors:
# Clear Deno cache
docker compose exec webclient deno cache --reload src/main.tsx

# Rebuild from scratch
docker compose down
docker compose build --no-cache webclient
docker compose up webclient
Ensure AUTH__JWT_SECRET is set in apps/services/.env.local:
# Verify environment variable
docker compose exec services env | grep AUTH

# Should output:
# AUTH__JWT_SECRET=your-secret-key-here

​
Next Steps

Full Installation Guide

Learn about Nix development, environment variables, and advanced setup

Architecture Overview

Understand how Aya’s frontend and backend work together

Frontend Development

Start building features with TanStack Start and React

Backend Development

Explore Go business logic and hexagonal architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us