matt/opnform-host-nginx
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Refactor Docker configuration and development setup

Browse Source 
- Update .dockerignore with comprehensive ignore patterns for API and client
- Modify docker-compose files to improve service configurations
- Enhance Nginx configuration for development and production environments
- Refactor Dockerfile.api with improved build process
- Add docker-setup.sh script for simplified Docker deployment
- Update update-credentials.vue page with improved UI
- Remove hCaptcha dependency from package-lock.json
- Update PHP configuration and entrypoint scripts
This commit is contained in:
Julien Nahum
2025-01-29 16:00:01 +01:00
parent bf85d8fa76
commit f7df6bc0d7
26 changed files with 1978 additions and 1749 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
docs/deployment/docker-development.mdx
View File

@@ -10,13 +10,15 @@ import CloudVersion from "/snippets/cloud-version.mdx";
## Overview
OpnForm provides a Docker-based development environment that offers:
- Hot-reload for both frontend and backend
- Hot Module Replacement (HMR) for real-time frontend updates
- Vue DevTools integration for debugging
- PHP hot reload for backend changes
- 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.
For details about the Docker architecture and components, see our [Docker Deployment](/deployment/docker) guide.
## Prerequisites
@@ -32,18 +34,19 @@ This is the recommended way to get started with OpnForm development.
cd OpnForm
```
2. Create environment files:
2. Run the setup script in development mode:
```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
chmod +x scripts/docker-setup.sh
./scripts/docker-setup.sh --dev
```
4. Access your development environment:
This script will:
- Create necessary environment files
- Pull or build required Docker images
- Start all containers in development mode
- Display access information
3. Access your development environment:
- Frontend: http://localhost:3000
- API: http://localhost/api
@@ -60,28 +63,54 @@ You will be prompted to change your email and password after your first login.
## Development Features
### Hot Reload
### Frontend Development
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`)
The development setup includes advanced frontend features:
- **Hot Module Replacement (HMR)**: Changes to Vue components and styles are instantly reflected without page reload
- **Vue DevTools**: Full integration for component inspection and state management debugging ([learn more](https://devtools.vuejs.org/))
- **Source Maps**: Enabled for easier debugging
- **Fast Refresh**: Preserves component state during updates
- **Error Overlay**: Displays errors directly in the browser
### File Structure
### Backend Development
The Laravel API service provides:
- **PHP Hot Reload**: Changes to PHP files are immediately available
- **Xdebug Integration**: Ready for step-by-step debugging
- **Laravel Telescope**: Available for request and queue monitoring
- **Artisan Commands**: Direct access to Laravel's CLI tools
<Note>
Queue workers require restart after code changes:
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml restart api-worker
```
</Note>
### Development URLs
- **Frontend**: http://localhost:3000
- Direct access to Nuxt dev server
- Includes HMR websocket connection
- Vue DevTools available
- **API**: http://localhost/api
- Handled by Nginx reverse proxy
- Automatic routing to PHP-FPM
- Supports file uploads and long requests
## 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
```
OpnForm/
├── api/ # Laravel API (mounted to api container)
│ ├── vendor/ # Preserved in container
│ └── storage/ # Mounted for logs and uploads
├── client/ # Nuxt frontend (mounted to ui container)
│ └── node_modules/ # Preserved in container
└── docker/ # Docker configuration files
```
## Common Tasks
@@ -95,6 +124,9 @@ docker compose -f docker-compose.yml -f docker-compose.dev.yml exec api php arti
# NPM commands
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec ui npm [command]
# Database commands
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec db psql -U forge
```
### Accessing Logs
@@ -105,35 +137,48 @@ View container logs:
# 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]
# Specific container (e.g., frontend)
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f ui
```
### Database Management
### Database Access
The PostgreSQL database is accessible:
- From containers: `host=db`
- From your machine: `localhost:5432`
- Default credentials: username=forge, password=forge, database=forge
- Default credentials:
```
Host: localhost
Port: 5432
Database: forge
Username: forge
Password: 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
# Clean everything and restart
./scripts/docker-setup.sh --dev
```
### Permission Issues
If you encounter permission issues with storage or vendor directories:
If you encounter permission issues:
```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
```
```
### HMR Issues
If hot reload isn't working:
1. Check browser console for WebSocket errors
2. Ensure ports 3000 and 24678 are available
3. Try restarting the UI container:
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml restart ui
```

221
docs/deployment/docker.mdx
View File

@@ -8,49 +8,34 @@ import CloudVersion from "/snippets/cloud-version.mdx";
<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**.
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
- Docker
- Docker Compose
## Quick Start
1. Clone the repository:
```bash
git clone https://github.com/JhumanJ/OpnForm.git
cd OpnForm
```
2. Set up environment files:
2. Run the setup script:
```bash
./scripts/setup-env.sh --docker
chmod +x scripts/docker-setup.sh
./scripts/docker-setup.sh
```
3. (Optional) Customize the environment variables:
You can modify two environment files to customize your OpnForm installation:
- The `.env` file in the `api` directory for backend configuration
- The `.env` file in the `client` directory for frontend configuration
For more information on available environment variables, please refer to our [Environment Variables](/configuration/environment-variables) page.
4. Start the application:
```bash
docker compose up -d
```
5. Access OpnForm at http://localhost
The script will:
- Create necessary environment files
- Pull required Docker images
- Start all containers in production mode
- Display access information
3. Access your OpnForm instance at `http://localhost`
### Initial Login
After installation, use these credentials to access the app:
After deployment, use these credentials to access the app:
- Email: `admin@opnform.com`
- Password: `password`
@@ -59,71 +44,171 @@ 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>
## Architecture
```mermaid
graph TD
A[Nginx Proxy] --> B[Frontend - Nuxt SSR]
A --> C[Backend - Laravel API]
C --> D[PostgreSQL]
C --> E[Redis]
C --> F[Queue Worker]
C --> G[Scheduler]
```
### Components
<Tabs>
<Tab title="Frontend">
The Nuxt frontend service:
- Server-Side Rendered application
- Built with Vue 3 and Tailwind CSS
- Handles dynamic rendering and client-side interactivity
- Optimized for production performance
</Tab>
<Tab title="Backend">
The Laravel API service:
- Handles business logic and data persistence
- Provides REST API endpoints
- Manages file uploads and processing
- Includes required PHP extensions (pgsql, redis, etc.)
- Configured for PostgreSQL and Redis connections
</Tab>
<Tab title="Workers">
Background processing services:
- **API Worker**: Processes queued jobs (emails, exports, etc.)
- **API Scheduler**: Handles scheduled tasks and periodic cleanups
- Both share the same codebase as the main API
</Tab>
<Tab title="Databases">
Data storage services:
- **PostgreSQL**: Primary database for all application data
- **Redis**: Used for:
- Session storage
- Cache
- Queue management
- Real-time features
</Tab>
<Tab title="Proxy">
The Nginx proxy service:
- Routes requests between frontend and backend
- Handles SSL termination
- Manages file upload limits
- Serves static assets
- Configured for optimal performance
</Tab>
</Tabs>
## Docker Images
OpnForm provides pre-built Docker images for easy deployment. You can find our official Docker images on Docker Hub:
OpnForm provides pre-built Docker images for easy deployment:
- [OpnForm API Image](https://hub.docker.com/r/jhumanj/opnform-api)
- [OpnForm Client Image](https://hub.docker.com/r/jhumanj/opnform-client)
We recommend using these official images for your OpnForm deployment.
### Building Custom Images
## Building Your Own Docker Images
By default, OpnForm uses pre-built images from Docker Hub. However, if you want to build the images yourself (for development or customization), you have two options:
### Option 1: Using Docker Compose (Recommended)
The simplest way to build the images is using Docker Compose:
While we recommend using the official images, you can build custom images if needed:
```bash
# Build all images
docker compose build
# Or build specific images
docker build -t opnform-api:local -f docker/Dockerfile.api .
docker build -t opnform-ui:local -f docker/Dockerfile.client .
```
This will build all the necessary images. You can then start the application as usual:
```bash
docker compose up -d
```
### Option 2: Building Images Manually
You can also build the images manually using the provided Dockerfiles:
1. Build the API image:
```bash
docker build -t opnform-api:local -f docker/Dockerfile.api .
```
2. Build the UI image:
```bash
docker build -t opnform-ui:local -f docker/Dockerfile.client .
```
If you build the images manually, make sure to update your docker-compose.override.yml to use these local images (see below).
### Overriding Docker Compose Configuration
You can override the default Docker Compose configuration by creating a `docker-compose.override.yml` file. This allows you to customize various aspects of the deployment without modifying the main `docker-compose.yml` file.
Example `docker-compose.override.yml`:
### Custom Configuration
Create a `docker-compose.override.yml` to customize your deployment:
```yaml
services:
api:
image: opnform-api:local
environment:
PHP_MEMORY_LIMIT: 1G
ui:
image: opnform-ui:local
api-worker:
image: opnform-api:local
ingress:
volumes:
- ./custom-nginx.conf:/etc/nginx/conf.d/default.conf
```
## Maintenance
### Clearing all resources
### Updates
To completely remove all Docker containers, networks, and volumes created by Docker Compose and also remove all images used by these services, you can use the following command:
1. Pull latest changes:
```bash
git pull origin main
```
2. Update containers:
```bash
docker compose pull
docker compose up -d
```
### Monitoring
View container logs:
```bash
# All containers
docker compose logs -f
# Specific container
docker compose logs -f api
```
docker compose down -v --rmi all
Monitor container health:
```bash
docker compose ps
```
## Troubleshooting
### Container Issues
If containers aren't starting:
```bash
# View detailed logs
docker compose logs -f
# Recreate containers
docker compose down
docker compose up -d
```
### Database Issues
If database connections fail:
```bash
# Check database status
docker compose exec db pg_isready
# View database logs
docker compose logs db
```
### Cache Issues
Clear various caches:
```bash
# Clear application cache
docker compose exec api php artisan cache:clear
# Clear config cache
docker compose exec api php artisan config:clear
# Clear route cache
docker compose exec api php artisan route:clear
```
### Permission Issues
Fix storage permissions:
```bash
docker compose exec api chown -R www-data:www-data storage
docker compose exec api chmod -R 775 storage
```