A small web-app with a darwin-core database, storing data from easydb5 and/or fylr to export via IPT to GBIF.

Easydb Webhooks should call the endpoints of this app, which will then query the modified entities from their and store or update them in the app's database. An IPT instance can then be used to export the database to GBIF.

• fylr-ipt-proxy
  • Development Setup
    • Prerequisites
    • Quick Start
    • Development Workflow
      • Access the PHP container
      • Run Symfony commands
      • View logs
      • Stop the application
      • Stop and remove all data (including database)
  • Production Deployment
    • Prerequisites
    • Production Deployment Steps
    • Production Updates
    • HTTP-Only Deployment (No HTTPS)
  • Docker Commands Reference
    • Container Management
    • Database Operations
    • Symfony Console Commands
    • Message Queue Management
  • Environment Configuration
    • Development Environment Variables
    • Production Environment Variables
  • Additional Documentation
  • Architecture
  • Troubleshooting
    • Common Issues
  • License

• Docker Engine 20.10+
• Docker Compose 2.0+
• Git

1. Clone the repository

   git clone https://github.com/BernhardWebstudio/fylr-ipt-proxy.git
   cd fylr-ipt-proxy

2. Configure environment variables (optional for development)

   cp .env.local.example .env.local
   # Edit .env.local with your custom settings if needed

3. Build and start the containers

   docker compose up -d --build

   This will start:

   • php: FrankenPHP web server with Symfony application
   • messenger_consumer: Background job processor
   • database: PostgreSQL database

4. Run database migrations

   docker compose exec php php bin/console doctrine:migrations:migrate

5. Access the application

   • Open your browser to http://localhost
   • The application runs with hot-reload enabled in development mode

docker compose exec php bash

docker compose exec php php bin/console <command>

# All services
docker compose logs -f

# Specific service
docker compose logs -f php
docker compose logs -f messenger_consumer

docker compose down

docker compose down -v

• A Linux server with Docker and Docker Compose installed
• A domain name pointing to your server's IP address
• SSH access to the server

1. Connect to your server

   ssh [email protected]

2. Clone the repository

   git clone https://github.com/BernhardWebstudio/fylr-ipt-proxy.git
   cd fylr-ipt-proxy

3. Set up environment variables

   Create a .env.prod.local file with production settings:

   nano .env.prod.local

   Add the following (replace with your actual values):

   APP_SECRET=your-cryptographically-secure-random-secret
   SERVER_NAME=your-domain.com
   CADDY_MERCURE_JWT_SECRET=another-cryptographically-secure-random-secret
   
   # Database configuration
   POSTGRES_DB=app
   POSTGRES_USER=app
   POSTGRES_PASSWORD=your-secure-database-password

4. Build production images

   docker compose -f compose.yaml -f compose.prod.yaml build --pull --no-cache

5. Start the application

   docker compose -f compose.yaml -f compose.prod.yaml up -d

6. Run database migrations

   docker compose exec php php bin/console doctrine:migrations:migrate --no-interaction

7. Verify deployment

   • Visit https://your-domain.com
   • Check that HTTPS certificate was automatically generated by Let's Encrypt
   • Monitor logs: docker compose logs -f

To update the application:

# Pull latest changes
git pull

# Rebuild images
docker compose -f compose.yaml -f compose.prod.yaml build --pull --no-cache

# Restart services
docker compose -f compose.yaml -f compose.prod.yaml up -d

# Run migrations if needed
docker compose exec php php bin/console doctrine:migrations:migrate --no-interaction

# Clear cache
docker compose exec php php bin/console cache:clear

If you don't need HTTPS (not recommended for production):

SERVER_NAME=:80 docker compose -f compose.yaml -f compose.prod.yaml up -d

# Start all services
docker compose up -d

# Stop all services
docker compose down

# Restart a specific service
docker compose restart php
docker compose restart messenger_consumer

# View running containers
docker compose ps

# View resource usage
docker compose stats

# Create a new migration
docker compose exec php php bin/console make:migration

# Run migrations
docker compose exec php php bin/console doctrine:migrations:migrate

# Check migration status
docker compose exec php php bin/console doctrine:migrations:status

# Access PostgreSQL CLI
docker compose exec database psql -U app -d app

# Clear cache
docker compose exec php php bin/console cache:clear

# List all routes
docker compose exec php php bin/console debug:router

# Clean up old jobs
docker compose exec php php bin/console app:cleanup-jobs

# View messenger consumer logs
docker compose logs -f messenger_consumer

# Restart message consumer
docker compose restart messenger_consumer

# Manual message consumption (for debugging)
docker compose exec php php bin/console messenger:consume async

# Check queue status (using helper script)
./scripts/messenger.sh status

# View failed messages
./scripts/messenger.sh failed

# Retry failed messages
./scripts/messenger.sh retry

The application uses the following environment variables (configured in compose.yaml):

For production, you must set the following in your .env.prod.local file:

• APP_SECRET: A cryptographically secure random string
• CADDY_MERCURE_JWT_SECRET: Another cryptographically secure random string
• SERVER_NAME: Your domain name (e.g., your-domain.com)
• POSTGRES_PASSWORD: A strong database password

Generate secure secrets using:

openssl rand -base64 32

• Docker Commands - Detailed Docker command reference
• Job Queue System - Message queue documentation
• Docker Messenger Setup - Messenger configuration for Docker
• Production Deployment Guide - Extended production deployment guide
• Troubleshooting - Common issues and solutions
• TLS Configuration - HTTPS and certificate setup
• Xdebug Setup - Debugging configuration

This application uses:

• Symfony 7.x: PHP framework
• FrankenPHP: Modern PHP application server with worker mode
• PostgreSQL: Relational database
• Symfony Messenger: Asynchronous message handling
• Docker: Containerization
• Caddy: Automatic HTTPS with Let's Encrypt

Port already in use

# Change the ports in compose.yaml or set environment variables:
HTTP_PORT=8080 HTTPS_PORT=8443 docker compose up -d

Database connection failed

# Wait for the database to be ready, then restart:
docker compose restart php

Permission issues

# Fix permissions on var directory:
docker compose exec php chown -R www-data:www-data var/

Cache issues

# Clear all caches:
docker compose exec php php bin/console cache:clear
docker compose exec php php bin/console cache:warmup

See LICENSE file for details.