dot-prompt

Installation & Setup

This guide covers different ways to set up dot-prompt for development - from quick Docker setup to running from source.

Quick Start with Docker

The fastest way to get started: 

# Clone the repository
git clone https://github.com/dot-prompt/dot-prompt.git
cd dot-prompt

# Start with Docker (easiest)
docker compose -f docker-compose.headless.yml up -d

# Or with the web UI
docker compose -f docker-compose.headed.yml up -d

Two Docker Images

  • headed - Includes the web UI for visual testing (default)
  • headless - API only, smaller image, better for servers

Building from Docker

Build and run the container manually: 

# Build the image
docker build -t dot-prompt:headless -f Dockerfile.headless .

# Or build the headed version
docker build -t dot-prompt:headed -f Dockerfile .

# Run the container
docker run -p 4000:4000 -v ./prompts:/app/prompts:ro dot-prompt:headless

Running from Source (Elixir)

If you want to run the Elixir application directly (for development or contributing):

Prerequisites

## Install Elixir (version 1.17+)
# macOS with Homebrew
brew install elixir

# Ubuntu/Debian
wget https://packages.erlang-solutions.com/ubuntu/erlang_solutions.asc
sudo apt-get update
sudo apt-get install esl-erlang

# Or use asdf (recommended)
asdf install elixir 1.17.0
asdf global elixir 1.17.0

## Install Node.js (for building assets, if using headed version)
# Using nvm
nvm install 22
nvm use 22

Setup

# Clone and setup
git clone https://github.com/dot-prompt/dot-prompt.git
cd dot-prompt

# Install dependencies
mix deps.get

# Run the application
mix phx.server

Environment Variables

# Development environment variables
export PORT=4000
export MIX_ENV=dev
export PROMPTS_DIR=./prompts
# Generate a secret key:
export SECRET_KEY_BASE=$(mix phx.gen.secret)

Directory Structure

Where to put your prompts: 

dot-prompt/
├── prompts/              # Your .prompt files go here
│   ├── hello.prompt
│   └── explainer.prompt
├── lib/                  # Elixir source code
├── priv/                 # Private assets
├── Dockerfile
├── Dockerfile.headless
├── docker-compose.yml
└── mix.exs

Create a test prompt to verify everything works: 

init do
  @version: 1.0
  @major: 1

  params:
    @name: str

end init

Hello, @name!

Testing Your Setup

Verify the API is running: 

# Test the API is running
curl http://localhost:4000/api/health

# List all prompts
curl http://localhost:4000/api/prompts

# Render a prompt
curl -X POST http://localhost:4000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "hello",
    "runtime": { "name": "World" }
  }'

Dev UI

If you're using the headed version: 

## Dev UI is available at:
# Headed version: http://localhost:4000
# The UI lets you:
# - Browse all your prompts
# - Test prompts with different parameters
# - See the compiled output in real-time

Troubleshooting

## Common Issues

### Port already in use
# Find what's using port 4000
lsof -i :4000
# Then kill it or use a different port

### Prompts not loading
# Check that PROMPTS_DIR is set correctly
# Ensure prompts have .prompt extension

### Secret key errors
# Generate a new secret key
mix phx.gen.secret

IDE Integration

Set up syntax highlighting in your editor: 

# Install the dot-prompt extension
# (when available)

# Or manually configure syntax highlighting
# Add to your VS Code settings.json:
{
  "files.associations": {
    "*.prompt": "elixir"
  }
}

CI/CD Integration

Example GitHub Actions workflow to test prompts: 

name: Test Prompts

on: [push, pull_request]

jobs:
  test-prompts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Start dot-prompt
        run: docker compose -f docker-compose.headless.yml up -d
        
      - name: Wait for API
        run: sleep 5
        
      - name: Test prompts
        run: |
          curl -X POST http://localhost:4000/api/render \
            -H "Content-Type: application/json" \
            -d '{"prompt":"hello","runtime":{"name":"Test"}}'

Next Steps