Developer docker setup (#683)

* Add build context to compose

Signed-off-by: Daniel Ekman <knegge@gmail.com>

* Update Docker documentation with build instructions

Enhance Docker deployment documentation by:
- Adding detailed instructions for building Docker images
- Providing two methods for image building (Docker Compose and manual)
- Clarifying how to use local images with docker-compose.override.yml

* Add development Docker configuration

Introduce development-specific Docker configuration:
- Create docker-compose.dev.yml for local development setup
- Add nginx.dev.conf with development CORS settings
- Update Dockerfile.api to support environment-specific dependency installation
- Configure development services with appropriate volumes and environment variables

* Improve Docker and Development Documentation

- Remove platform-specific ARM64 constraints in docker-compose.dev.yml
- Enhance Nginx configuration with improved proxy and HMR settings
- Update documentation for development setup and Docker deployment
- Add new Docker development documentation page
- Refactor getting started guide with clearer development instructions

* Enhance Docker configuration and CI/CD pipeline

- Update Docker Compose files with improved service configurations
- Add database healthcheck in docker-compose.yml
- Refactor GitHub Actions workflow for Docker image publishing
- Optimize Dockerfile.api with multi-stage build and environment-specific configurations
- Update Nginx configuration for development and production environments

* Add GitHub Actions permissions for Docker image publishing

Configure GitHub Actions workflow with explicit read and write permissions for content and packages to improve security and clarity of Docker image deployment process

---------

Signed-off-by: Daniel Ekman <knegge@gmail.com>
Co-authored-by: Daniel Ekman <knegge@gmail.com>
This commit is contained in:
Julien Nahum 2025-01-28 17:52:48 +01:00 committed by GitHub
parent ae74f33a27
commit bf85d8fa76
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 466 additions and 74 deletions

View File

@ -1,37 +1,70 @@
name: Publish Docker image name: Publish Docker Images
on: on:
push: push:
tags: tags:
- "v*" - "v*"
branches:
- main
paths:
- "api/**"
- "client/**"
- "docker/**"
- "docker-compose*.yml"
workflow_dispatch:
permissions:
contents: read
packages: write
jobs: jobs:
push_to_registry: push_to_registry:
name: Push Docker image to Docker Hub name: Push Docker images to Docker Hub
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: Get tag name - name: Get version info
run: | run: |
( if [[ $GITHUB_REF == refs/tags/* ]]; then
echo "TAG_NAME=${GITHUB_REF#refs/*/v}"; echo "VERSION=${GITHUB_REF#refs/*/v}" >> $GITHUB_ENV
echo "DOCKER_UI_REPO=${{secrets.DOCKER_UI_REPO}}" echo "API_TAGS=${{secrets.DOCKER_API_REPO}}:latest,${{secrets.DOCKER_API_REPO}}:${GITHUB_REF#refs/*/v}" >> $GITHUB_ENV
echo "DOCKER_API_REPO=${{secrets.DOCKER_API_REPO}}" echo "UI_TAGS=${{secrets.DOCKER_UI_REPO}}:latest,${{secrets.DOCKER_UI_REPO}}:${GITHUB_REF#refs/*/v}" >> $GITHUB_ENV
) >> $GITHUB_ENV else
echo "VERSION=dev" >> $GITHUB_ENV
echo "API_TAGS=${{secrets.DOCKER_API_REPO}}:dev" >> $GITHUB_ENV
echo "UI_TAGS=${{secrets.DOCKER_UI_REPO}}:dev" >> $GITHUB_ENV
fi
- name: Check out the repo - name: Check out the repo
uses: actions/checkout@v3 uses: actions/checkout@v3
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Docker Hub - name: Log in to Docker Hub
run: docker login -u "${{ secrets.DOCKER_USERNAME }}" -p "${{ secrets.DOCKER_ACCESS_TOKEN }}" uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_ACCESS_TOKEN }}
- name: Build docker api image - name: Build and push API image
run: docker build -f docker/Dockerfile.api . -t $DOCKER_API_REPO:latest -t $DOCKER_API_REPO:$TAG_NAME uses: docker/build-push-action@v5
with:
context: .
file: docker/Dockerfile.api
platforms: linux/amd64,linux/arm64
push: true
build-args: |
APP_ENV=${{ env.VERSION == 'dev' && 'local' || 'production' }}
tags: ${{ env.API_TAGS }}
- name: Build docker ui image - name: Build and push Client image
run: docker build -f docker/Dockerfile.client . -t $DOCKER_UI_REPO:latest -t $DOCKER_UI_REPO:$TAG_NAME uses: docker/build-push-action@v5
with:
- name: Push Docker api image context: .
run: docker push $DOCKER_API_REPO:latest && docker push $DOCKER_API_REPO:$TAG_NAME file: docker/Dockerfile.client
platforms: linux/amd64,linux/arm64
- name: Push Docker ui image push: true
run: docker push $DOCKER_UI_REPO:latest && docker push $DOCKER_UI_REPO:$TAG_NAME tags: ${{ env.UI_TAGS }}

11
.gitignore vendored
View File

@ -9,3 +9,14 @@ public/.DS_Store
*.DS_Store *.DS_Store
docker-compose.override.yml docker-compose.override.yml
/.make.* /.make.*
# Environment files
.env
api/.env
client/.env
.env.*
api/.env.*
client/.env.*
!.env.example
!api/.env.example
!client/.env.example

77
docker-compose.dev.yml Normal file
View File

@ -0,0 +1,77 @@
services:
api: &api-base
image: jhumanj/opnform-api:dev
build:
context: .
dockerfile: docker/Dockerfile.api
args:
APP_ENV: local
volumes:
- ./api:/usr/share/nginx/html:delegated
- /usr/share/nginx/html/vendor # Exclude vendor directory from the mount
- ./api/storage:/usr/share/nginx/html/storage:delegated # Mount storage directory directly
environment:
DB_HOST: db
REDIS_HOST: redis
DB_DATABASE: ${DB_DATABASE:-forge}
DB_USERNAME: ${DB_USERNAME:-forge}
DB_PASSWORD: ${DB_PASSWORD:-forge}
DB_CONNECTION: ${DB_CONNECTION:-pgsql}
FILESYSTEM_DISK: local
LOCAL_FILESYSTEM_VISIBILITY: public
APP_ENV: local
PHP_IDE_CONFIG: "serverName=Docker"
XDEBUG_MODE: "${XDEBUG_MODE:-off}"
XDEBUG_CONFIG: "client_host=host.docker.internal"
APP_URL: "http://localhost"
depends_on:
db:
condition: service_healthy
ui:
image: jhumanj/opnform-client:dev
build:
context: .
dockerfile: docker/Dockerfile.client
command: sh -c "npm install && NITRO_HOST=0.0.0.0 NITRO_PORT=3000 npm run dev"
volumes:
- ./client:/app:delegated
- /app/node_modules # Keep container's node_modules
environment:
NODE_ENV: development
NUXT_PUBLIC_APP_ENV: development
HOST: "0.0.0.0"
PORT: 3000
# HMR settings
CHOKIDAR_USEPOLLING: "true"
WATCHPACK_POLLING: "true"
VITE_HMR_HOST: "localhost"
VITE_HMR_PORT: 24678
# API settings
NUXT_PUBLIC_APP_URL_BASE: "http://localhost"
NUXT_PUBLIC_API_BASE: "http://localhost/api"
extra_hosts:
- "host.docker.internal:host-gateway"
ports:
- "3000:3000" # Main dev server
- "24678:24678" # Vite HMR port
ingress:
volumes:
- ./docker/nginx.dev.conf:/etc/nginx/templates/default.conf.template
environment:
NGINX_HOST: localhost
NGINX_PORT: 80
ports:
- "80:80"
depends_on:
- api
- ui
api-worker:
<<: *api-base
environment:
IS_API_WORKER: "true"
depends_on:
db:
condition: service_healthy

View File

@ -5,6 +5,8 @@ services:
build: build:
context: . context: .
dockerfile: docker/Dockerfile.api dockerfile: docker/Dockerfile.api
args:
APP_ENV: production
environment: &api-environment # Add this anchor environment: &api-environment # Add this anchor
DB_HOST: db DB_HOST: db
REDIS_HOST: redis REDIS_HOST: redis
@ -24,6 +26,8 @@ services:
build: build:
context: . context: .
dockerfile: docker/Dockerfile.api dockerfile: docker/Dockerfile.api
args:
APP_ENV: production
command: php artisan queue:work command: php artisan queue:work
environment: environment:
<<: *api-environment <<: *api-environment
@ -50,6 +54,11 @@ services:
POSTGRES_DB: ${DB_DATABASE:-forge} POSTGRES_DB: ${DB_DATABASE:-forge}
POSTGRES_USER: ${DB_USERNAME:-forge} POSTGRES_USER: ${DB_USERNAME:-forge}
POSTGRES_PASSWORD: ${DB_PASSWORD:-forge} POSTGRES_PASSWORD: ${DB_PASSWORD:-forge}
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-forge}"]
interval: 5s
timeout: 5s
retries: 5
volumes: volumes:
- postgres-data:/var/lib/postgresql/data - postgres-data:/var/lib/postgresql/data

View File

@ -1,28 +1,50 @@
# Stage 1: Composer dependencies
FROM composer:latest as composer
WORKDIR /app
COPY api/composer.* ./
ARG APP_ENV=production
RUN if [ "$APP_ENV" = "production" ]; then \
composer install --ignore-platform-req=php --no-dev --optimize-autoloader; \
else \
composer install --ignore-platform-req=php --optimize-autoloader; \
fi
# Stage 2: Final image
FROM php:8.3-fpm FROM php:8.3-fpm
# syntax=docker/dockerfile:1.3-labs # Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \ RUN apt-get update && apt-get install -y \
libzip-dev \ git \
curl \
libpng-dev \ libpng-dev \
postgresql-client \ libonig-dev \
libxml2-dev \
zip \
unzip \
libpq-dev \ libpq-dev \
&& apt-get clean \ && docker-php-ext-install pdo_pgsql mbstring exif pcntl bcmath gd \
&& rm -rf /var/lib/apt/lists/*
COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer
ENV COMPOSER_ALLOW_SUPERUSER=1
RUN docker-php-ext-install pdo pgsql pdo_pgsql gd bcmath zip \
&& pecl install redis \ && pecl install redis \
&& docker-php-ext-enable redis && docker-php-ext-enable redis
WORKDIR /usr/share/nginx/html/ # Install xdebug if not in production
ARG APP_ENV=production
RUN if [ "$APP_ENV" != "production" ]; then \
pecl install xdebug && \
docker-php-ext-enable xdebug; \
fi
# Combine multiple ADD commands into one # Configure PHP
COPY api/composer.json api/composer.lock api/artisan ./ COPY docker/php/php.ini /usr/local/etc/php/conf.d/app.ini
COPY api/app ./app COPY docker/php/php-fpm.conf /usr/local/etc/php-fpm.d/www.conf
WORKDIR /usr/share/nginx/html
# Copy application files
COPY api/artisan artisan
COPY api/bootstrap ./bootstrap COPY api/bootstrap ./bootstrap
COPY api/config ./config COPY api/config ./config
COPY api/app ./app
COPY api/database ./database COPY api/database ./database
COPY api/public ./public COPY api/public ./public
COPY api/routes ./routes COPY api/routes ./routes
@ -30,15 +52,13 @@ COPY api/tests ./tests
COPY api/resources ./resources COPY api/resources ./resources
COPY api/storage ./storage COPY api/storage ./storage
RUN sed 's_@php artisan package:discover_/bin/true_;' -i composer.json \ # Copy vendor directory from composer stage
&& composer install --ignore-platform-req=php --no-dev --optimize-autoloader \ COPY --from=composer /app/vendor ./vendor
&& composer clear-cache \
&& php artisan package:discover --ansi \ # Set permissions
&& chmod -R 775 storage \ RUN chmod -R 775 storage \
&& chown -R www-data:www-data storage \ && chmod -R 775 bootstrap/cache \
&& mkdir -p storage/framework/sessions storage/framework/views storage/framework/cache \ && chown -R www-data:www-data /usr/share/nginx/html
&& chown -R www-data:www-data storage \
&& chmod -R 775 storage
COPY docker/php-fpm-entrypoint /usr/local/bin/opnform-entrypoint COPY docker/php-fpm-entrypoint /usr/local/bin/opnform-entrypoint
RUN chmod a+x /usr/local/bin/* RUN chmod a+x /usr/local/bin/*

View File

@ -4,38 +4,36 @@ map $original_uri $api_uri {
} }
server { server {
listen 80; listen 80;
server_name opnform; server_name opnform;
root /app/public; root /usr/share/nginx/html/public;
access_log /dev/stdout; access_log /dev/stdout;
error_log /dev/stderr error; error_log /dev/stderr error;
index index.html index.htm index.php; index index.html index.htm index.php;
location / { location / {
proxy_http_version 1.1; proxy_http_version 1.1;
proxy_pass http://ui:3000; proxy_pass http://ui:3000;
proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header Upgrade $http_upgrade; proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade"; proxy_set_header Connection "Upgrade";
} }
location ~/(api|open|local\/temp|forms\/assets)/ { location ~/(api|open|local\/temp|forms\/assets)/ {
set $original_uri $uri; try_files $uri $uri/ /index.php?$query_string;
try_files $uri $uri/ /index.php$is_args$args; }
}
location ~ \.php$ { location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$; fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass api:9000; fastcgi_pass api:9000;
fastcgi_index index.php; fastcgi_index index.php;
include fastcgi_params; include fastcgi_params;
#fastcgi_param SCRIPT_FILENAME /usr/share/nginx/html/$fastcgi_script_name; fastcgi_param SCRIPT_FILENAME /usr/share/nginx/html/public/index.php;
fastcgi_param SCRIPT_FILENAME /usr/share/nginx/html/public/index.php; fastcgi_param REQUEST_URI $api_uri;
fastcgi_param REQUEST_URI $api_uri; }
}
} }

73
docker/nginx.dev.conf Normal file
View File

@ -0,0 +1,73 @@
map $original_uri $api_uri {
~^/api(/.*$) $1;
default $original_uri;
}
server {
listen 80;
server_name opnform;
root /usr/share/nginx/html/public;
access_log /dev/stdout;
error_log /dev/stderr error;
index index.html index.htm index.php;
# Development CORS headers
add_header 'Access-Control-Allow-Origin' 'http://localhost:3000' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS, PATCH' always;
add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-XSRF-TOKEN' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;
# Handle preflight requests
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' 'http://localhost:3000' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS, PATCH' always;
add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-XSRF-TOKEN' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
add_header 'Access-Control-Max-Age' 1728000;
add_header 'Content-Type' 'text/plain charset=UTF-8';
add_header 'Content-Length' 0;
return 204;
}
# Development proxy settings
location / {
proxy_http_version 1.1;
proxy_pass http://ui:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
proxy_buffering off;
}
# HMR websocket support
location /_nuxt {
proxy_pass http://ui:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
location ~/(api|open|local\/temp|forms\/assets)/ {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass api:9000;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME /usr/share/nginx/html/public/index.php;
fastcgi_param REQUEST_URI $api_uri;
}
}

View File

@ -1,8 +1,25 @@
--- ---
title: "Getting Started with Contributing" title: Getting Started
description: "Learn how to contribute to OpnForm" description: Learn how to contribute to OpnForm
--- ---
## Development Setup
### Docker Setup (Recommended)
The easiest way to get started with OpnForm development is to use our Docker-based development environment. It provides:
- Hot-reload for both frontend and backend
- All necessary services pre-configured
- Consistent development environment across all platforms
Follow our [Docker Development Setup](/deployment/docker-development) guide to get started.
### Manual Setup
If you prefer not to use Docker or need a custom setup, you can follow our [Local Deployment](/deployment/local-deployment#manual-setup) guide for manual installation instructions.
## Contributing Guidelines
Welcome to the OpnForm contributing guide! Here are some helpful links to get you started: Welcome to the OpnForm contributing guide! Here are some helpful links to get you started:
<CardGroup cols={2}> <CardGroup cols={2}>

View File

@ -0,0 +1,139 @@
---
title: "Docker Development Setup"
description: "Set up OpnForm locally for development using Docker"
---
import CloudVersion from "/snippets/cloud-version.mdx";
<CloudVersion/>
## Overview
OpnForm provides a Docker-based development environment that offers:
- Hot-reload for both frontend and backend
- Xdebug support for PHP debugging
- Automatic dependency management
- PostgreSQL database and Redis setup
- Nginx reverse proxy configuration
This is the recommended way to get started with OpnForm development.
## Prerequisites
- Docker and Docker Compose installed on your machine
- Git installed
- Basic understanding of Docker concepts
## Quick Start
1. Clone the repository:
```bash
git clone https://github.com/JhumanJ/OpnForm.git
cd OpnForm
```
2. Create environment files:
```bash
./scripts/setup-env.sh
```
This will create the necessary `.env` files for both the API and client. See our [Environment Variables](/configuration/environment-variables) guide for configuration details.
3. Start the development environment:
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
```
4. Access your development environment:
- Frontend: http://localhost:3000
- API: http://localhost/api
### Initial Login
After starting the development environment, use these credentials to access the app:
- Email: `admin@opnform.com`
- Password: `password`
You will be prompted to change your email and password after your first login.
<Note>Public registration is disabled in the self-hosted version. Use the admin account to invite additional users.</Note>
## Development Features
### Hot Reload
The development setup includes hot reload capabilities:
- Frontend (Nuxt.js): Changes to files in the `client` directory trigger automatic rebuilds
- Backend (Laravel): Changes to files in the `api` directory are immediately reflected, except for queued jobs which require restarting the api-worker container (`docker compose -f docker-compose.yml -f docker-compose.dev.yml restart api-worker`)
### File Structure
The development setup mounts your local directories into the containers:
- `./api`: Mounted to the API container with vendor directory preserved
- `./client`: Mounted to the UI container with node_modules preserved
- Database and Redis data are persisted through Docker volumes
### Container Services
The development environment includes:
- `api`: Laravel API service with hot reload
- `ui`: Nuxt.js frontend with HMR
- `api-worker`: Laravel queue worker
- `db`: PostgreSQL database
- `redis`: Redis server
- `ingress`: Nginx reverse proxy
## Common Tasks
### Running Commands
To run commands in the containers:
```bash
# Laravel Artisan commands
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec api php artisan [command]
# NPM commands
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec ui npm [command]
```
### Accessing Logs
View container logs:
```bash
# All containers
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f
# Specific container
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f [service]
```
### Database Management
The PostgreSQL database is accessible:
- From containers: `host=db`
- From your machine: `localhost:5432`
- Default credentials: username=forge, password=forge, database=forge
## Troubleshooting
### Container Issues
If containers aren't starting properly:
```bash
# Remove all containers and volumes
docker compose down -v
# Rebuild and start
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
```
### Permission Issues
If you encounter permission issues with storage or vendor directories:
```bash
# Fix storage permissions
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec api chmod -R 775 storage
# Fix vendor permissions
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec api chmod -R 775 vendor
```

View File

@ -1,12 +1,16 @@
--- ---
title: "Docker" title: "Docker Deployment"
description: "OpnForm can be easily set up using Docker. We provide pre-built images on Docker Hub, which is the recommended method for most users." description: "Deploy OpnForm using Docker"
--- ---
import CloudVersion from "/snippets/cloud-version.mdx"; import CloudVersion from "/snippets/cloud-version.mdx";
<CloudVersion/> <CloudVersion/>
<Tip>
This guide is for deploying OpnForm on a production server. If you're looking to **develop OpnForm locally**, check out our [Docker Development Setup](/deployment/docker-development) guide which provides **hot-reload and other development features**.
</Tip>
## Prerequisites ## Prerequisites
- Docker - Docker

View File

@ -7,6 +7,16 @@ import CloudVersion from "/snippets/cloud-version.mdx";
<CloudVersion/> <CloudVersion/>
## Docker Development Setup (Recommended)
We recommend using our Docker-based development environment for the easiest setup experience. It provides hot-reload, debugging support, and all necessary services pre-configured.
See our [Docker Development Setup](/deployment/docker-development) guide to get started with Docker.
## Manual Setup
If you prefer to set up OpnForm manually or can't use Docker, follow the instructions below.
## Requirements ## Requirements
Before proceeding with the local deployment, ensure you have the following prerequisites installed on your system: Before proceeding with the local deployment, ensure you have the following prerequisites installed on your system:

View File

@ -73,6 +73,7 @@
"group": "Deployment", "group": "Deployment",
"pages": [ "pages": [
"deployment/docker", "deployment/docker",
"deployment/docker-development",
"deployment/local-deployment", "deployment/local-deployment",
"deployment/cloud-vs-self-hosting" "deployment/cloud-vs-self-hosting"
] ]