Deployment

This guide provides step-by-step instructions for deploying the API server and its associated background workers using the provided Docker configuration. This approach is recommended for both local development and production environments.

Prerequisites

1. Docker & Docker Compose: Ensure Docker and Docker Compose are installed on your server or local machine.
2. .env File: You must have a .env file in the root of the project, configured with your production secrets and settings. Start by copying .env.example to .env.

Step 1: Production Configuration

Before you can deploy, you must complete two essential configuration steps.

a. Configure Production Environment Variables

In your production environment, you will not use a .env file. Instead, you must configure the environment variables directly in your chosen hosting provider's interface. This is a critical step for security and proper configuration.

For a detailed explanation of each required variable, please see the Configure Environment Variables Guide.

b. Configure CORS

For the Web Dashboard to communicate with your API in production, you must correctly configure Cross-Origin Resource Sharing (CORS) by setting the CORS_ALLOWED_ORIGIN environment variable.

For instructions, see the Configure CORS Guide.

Step 2: Build the Docker Image

Navigate to the project's root directory in your terminal and run the build command:

docker compose build

This command reads the Dockerfile and docker-compose.yml to build a single, optimized production image named after your project directory (e.g., flutter-news-app-api-server-full-source-code_api-server). This image contains the compiled server and all worker executables.

Step 3: Run the Application Services

The application requires two long-running services to function correctly when using the local storage provider: the API server itself and the finalization worker.

Start these services in detached mode (-d):

docker compose up -d api-server finalize-worker

• api-server: Starts the main Dart Frog server, which will be accessible on port 8080 of the host machine.
• finalize-worker: Starts the background worker responsible for processing local file uploads. This is essential for the media system to work.

You can view the logs for these services at any time:

# View logs for the API server
docker compose logs -f api-server

# View logs for the finalization worker
docker compose logs -f finalize-worker

Step 4: Running Scheduled Tasks (Workers)

The media_cleanup_worker and analytics_sync_worker are designed to be run periodically, not as long-running services. Use docker compose run to execute them as one-off tasks.

Manual Execution

• To run the media cleanup worker:

  docker compose run --rm cleanup-worker

• To run the analytics sync worker:

  docker compose run --rm analytics-worker

The --rm flag is important as it automatically removes the container after the task is complete, preventing a buildup of stopped containers.

Automated Execution with Cron

For a production environment, you should automate these tasks using a scheduler like cron.

1. Open your crontab for editing:

   crontab -e

2. Add entries to schedule the workers. The following example runs the analytics sync every hour and the media cleanup once a day at 3:05 AM.

   # Example crontab entries
   # NOTE: Replace /path/to/your/project with the actual absolute path.
   
   # Run the analytics sync worker every hour at the 5-minute mark.
   5 * * * * cd /path/to/your/project && /usr/bin/docker-compose run --rm analytics-worker >> /var/log/cron.log 2>&1
   
   # Run the media cleanup worker once daily at 3:05 AM.
   5 3 * * * cd /path/to/your/project && /usr/bin/docker-compose run --rm cleanup-worker >> /var/log/cron.log 2>&1

   Important:

   • You must use absolute paths for docker-compose and cd into your project directory.
   • >> /var/log/cron.log 2>&1 redirects all output (both standard and error) to a log file, which is crucial for debugging.

Step 5: Updating the Application

To deploy a new version of the application:

1. Pull the latest changes from your version control system (e.g., Git).

   git pull

2. Re-build the image and restart the services with the updated code. Docker Compose will intelligently only rebuild and restart the services whose code has changed.

   docker compose up --build -d api-server finalize-worker