next.orly.dev/scripts/README.md

ORLY Scripts Directory

This directory contains automation scripts for building, testing, and deploying ORLY.

Quick Reference

Dgraph Integration Testing

# Local testing (requires dgraph server)
./dgraph-start.sh           # Start dgraph server
./test-dgraph.sh            # Run dgraph package tests
./test-dgraph.sh --relay-tester  # Run tests + relay-tester

# Docker testing (containers for everything)
./docker-build.sh           # Build ORLY docker image
./test-docker.sh            # Run integration tests in containers
./test-docker.sh --relay-tester --keep-running  # Full test, keep running

Build & Deploy

./build-all-platforms.sh    # Build for multiple platforms
./deploy.sh                 # Deploy to systemd
./update-embedded-web.sh    # Build and embed web UI

Script Descriptions

Dgraph Testing Scripts

dgraph-start.sh

Starts dgraph server using docker-compose for local testing.

Usage:

./dgraph-start.sh

What it does:

• Checks if dgraph is already running
• Starts dgraph via docker-compose
• Waits for health check
• Shows endpoints and commands

dgraph-docker-compose.yml

Docker Compose configuration for standalone dgraph server.

Ports:

• 8080: HTTP API
• 9080: gRPC (ORLY connects here)
• 8000: Ratel UI

test-dgraph.sh

Runs dgraph package tests against a running dgraph server.

Usage:

./test-dgraph.sh                    # Just tests
./test-dgraph.sh --relay-tester     # Tests + relay-tester

Requirements:

• Dgraph server running at ORLY_DGRAPH_URL (default: localhost:9080)
• Go 1.21+

Docker Integration Scripts

docker-build.sh

Builds Docker images for ORLY and optionally relay-tester.

Usage:

./docker-build.sh                   # ORLY only
./docker-build.sh --with-tester     # ORLY + relay-tester

Output:

• orly:latest
• orly-relay-tester:latest (if --with-tester)

docker-compose-test.yml

Full-stack docker-compose with dgraph, ORLY, and relay-tester.

Services:

• dgraph: Database backend
• orly: Relay with dgraph backend
• relay-tester: Protocol tests (optional, profile: test)

Features:

• Health checks for all services
• Dependency management (ORLY waits for dgraph)
• Custom network with DNS
• Persistent volumes

test-docker.sh

Comprehensive integration testing in Docker containers.

Usage:

./test-docker.sh                              # Basic test
./test-docker.sh --relay-tester               # Run relay-tester
./test-docker.sh --keep-running               # Keep containers running
./test-docker.sh --skip-build                 # Use existing images
./test-docker.sh --relay-tester --keep-running  # Full test + keep running

What it does:

1. Stops any existing containers
2. Optionally rebuilds images
3. Starts dgraph and waits for health
4. Starts ORLY and waits for health
5. Verifies connectivity
6. Optionally runs relay-tester
7. Shows status and endpoints
8. Cleanup (unless --keep-running)

Build Scripts

build-all-platforms.sh

Cross-compiles ORLY for multiple platforms.

Platforms:

• linux/amd64
• linux/arm64
• darwin/amd64
• darwin/arm64

Output: dist/ directory with platform-specific binaries

update-embedded-web.sh

Builds the Svelte web UI and embeds it in ORLY binary.

Steps:

1. Builds web UI with bun
2. Generates embedded assets
3. Rebuilds ORLY with embedded UI

Deployment Scripts

deploy.sh

Automated deployment with systemd service.

What it does:

1. Installs Go if needed
2. Builds ORLY with embedded web UI
3. Installs to ~/.local/bin/orly
4. Creates systemd service
5. Enables and starts service
6. Sets up port binding capabilities

Test Scripts

test.sh

Runs all Go tests in the project.

Usage:

./test.sh          # All tests
TEST_LOG=1 ./test.sh  # With logging

Environment Variables

Common Variables

# Dgraph
export ORLY_DGRAPH_URL=localhost:9080    # Dgraph endpoint
export ORLY_DB_TYPE=dgraph               # Use dgraph backend

# Logging
export ORLY_LOG_LEVEL=debug              # Log verbosity
export TEST_LOG=1                        # Enable test logging

# Server
export ORLY_PORT=3334                    # HTTP/WebSocket port
export ORLY_LISTEN=0.0.0.0               # Listen address

# Data
export ORLY_DATA_DIR=/path/to/data       # Data directory

Script-Specific Variables

# Docker scripts
export SKIP_BUILD=true                   # Skip image rebuild
export KEEP_RUNNING=true                 # Don't cleanup containers

# Dgraph scripts
export DGRAPH_VERSION=latest             # Dgraph image tag

File Organization

scripts/
├── README.md                    # This file
├── DGRAPH_TESTING.md           # Dgraph testing guide
├── DOCKER_TESTING.md           # Docker testing guide
│
├── dgraph-start.sh             # Start dgraph server
├── dgraph-docker-compose.yml   # Dgraph docker config
├── test-dgraph.sh              # Run dgraph tests
│
├── docker-build.sh             # Build docker images
├── docker-compose-test.yml     # Full stack docker config
├── test-docker.sh              # Run docker integration tests
│
├── build-all-platforms.sh      # Cross-compile
├── deploy.sh                   # Deploy to systemd
├── update-embedded-web.sh      # Build web UI
└── test.sh                     # Run Go tests

Workflows

Local Development with Dgraph

# 1. Start dgraph
./scripts/dgraph-start.sh

# 2. Run ORLY locally with dgraph
export ORLY_DB_TYPE=dgraph
export ORLY_DGRAPH_URL=localhost:9080
./orly

# 3. Test changes
go run cmd/relay-tester/main.go -url ws://localhost:3334

# 4. Run unit tests
./scripts/test-dgraph.sh

Docker Development

# 1. Make changes
vim pkg/dgraph/save-event.go

# 2. Build and test in containers
./scripts/test-docker.sh --relay-tester --keep-running

# 3. Make more changes

# 4. Rebuild just ORLY
cd scripts
docker-compose -f docker-compose-test.yml up -d --build orly

# 5. View logs
docker logs orly-relay -f

# 6. Stop when done
docker-compose -f docker-compose-test.yml down

CI/CD Testing

# Quick test (no containers)
./scripts/test.sh

# Full integration test
./scripts/test-docker.sh --relay-tester

# Build for deployment
./scripts/build-all-platforms.sh

Production Deployment

# Deploy with systemd
./scripts/deploy.sh

# Check status
systemctl status orly

# View logs
journalctl -u orly -f

# Update
./scripts/deploy.sh  # Rebuilds and restarts

Troubleshooting

Dgraph Not Available

# Check if running
docker ps | grep dgraph

# Start it
./scripts/dgraph-start.sh

# Check logs
docker logs dgraph-orly-test -f

Port Conflicts

# Find what's using port 3334
lsof -i :3334
netstat -tlnp | grep 3334

# Kill process
kill $(lsof -t -i :3334)

# Or use different port
export ORLY_PORT=3335

Docker Build Failures

# Clear docker cache
docker builder prune

# Rebuild from scratch
docker build --no-cache -t orly:latest -f Dockerfile .

# Check Dockerfile syntax
docker build --dry-run -f Dockerfile .

Permission Issues

# Fix script permissions
chmod +x scripts/*.sh

# Fix docker socket
sudo usermod -aG docker $USER
newgrp docker

Best Practices

1. Always use scripts from project root

   ./scripts/test-docker.sh  # Good
   cd scripts && ./test-docker.sh  # May have path issues
   

2. Check prerequisites before running

   # Check docker
   docker --version
   docker-compose --version
   
   # Check dgraph
   curl http://localhost:9080/health
   

3. Clean up after testing

   # Stop containers
   cd scripts && docker-compose -f docker-compose-test.yml down
   
   # Remove volumes if needed
   docker-compose -f docker-compose-test.yml down -v
   

4. Use --keep-running for debugging

   ./scripts/test-docker.sh --keep-running
   # Inspect, debug, make changes
   docker-compose -f scripts/docker-compose-test.yml down
   

5. Check logs on failures

   # Container logs
   docker logs orly-relay --tail 100
   
   # Test output
   ./scripts/test-dgraph.sh 2>&1 | tee test.log
   

Related Documentation

• Dgraph Testing Guide
• Docker Testing Guide
• Package Tests
• Main Implementation Status

Contributing

When adding new scripts:

1. Add executable permission

   chmod +x scripts/new-script.sh
   

2. Use bash strict mode

   #!/bin/bash
   set -e  # Exit on error
   

3. Add help text

   if [ "$1" == "--help" ]; then
       echo "Usage: $0 [options]"
       exit 0
   fi
   

4. Document in this README

   • Add to appropriate section
   • Include usage examples
   • Note any requirements

5. Test on fresh system

   # Use Docker to test
   docker run --rm -v $(pwd):/app -w /app ubuntu:latest ./scripts/new-script.sh