Server Project Organization Guide

Server Project Organization Guide

Server: production-server-01 (Hetzner) Last Updated: 2026-04-11

---

Overview

This guide explains the directory organization patterns used on our production server, helping you understand where projects are located and how they’re deployed.

---

Directory Organization Patterns

Our server uses two main directories for hosting applications, each serving different deployment types:

/var/www/ - Traditional Web Applications

Purpose: Direct deployment applications running on the host system

Characteristics:

• Applications run as systemd services or PM2 processes
• Dependencies installed directly on the host
• Share host system resources (PostgreSQL, Redis, Node.js, Python)
• Managed via systemd or process managers

Examples:

• KopanoWorks - Construction project management (pnpm monorepo)
• ProspectIQ - Lead enrichment platform (FastAPI + Celery)
• ThriveSend - Email marketing platform (Node.js)
• SANSA - Space education platform (Frontend + Backend)

/opt/ - Containerized Applications

Purpose: Self-contained Docker-based applications

Characteristics:

• Applications run in Docker containers via Docker Compose
• All dependencies bundled inside containers
• Isolated environments with their own databases, web servers, etc.
• Managed via docker compose commands

Examples:

• Polelo DMS - Document management system (Laravel + Docker)
• AutoSlip - Automated slip system
• Buka - Containerized application

---

Why This Separation?

This organization follows Linux best practices:

Directory	Purpose	Standard Usage
/var/www/	Variable data for web services	Web content, applications served by web servers
/opt/	Optional/add-on software packages	Self-contained third-party or containerized applications

Benefits:

• ✅ Clear separation between deployment types
• ✅ Easy to understand how each project is managed
• ✅ Prevents confusion during maintenance and troubleshooting
• ✅ Follows industry-standard conventions

---

Complete Project Inventory

/var/www/ Projects (Direct Deployment)

Project	Location	Type	Port(s)	Domain
KopanoWorks	/var/www/kopanoworks/	pnpm monorepo (Express + Next.js + React Native)	Various	kopanoworks.isutech.co.za, admin.kopanoworks.isutech.co.za
ProspectIQ	/var/www/prospect-iq/	FastAPI + Celery	8002, 3002	prospectiq.isutech.co.za
ThriveSend	/var/www/thrivesend/	Node.js	Various	thrivesend.isutech.co.za
SANSA Frontend	/var/www/sansa-frontend/	Next.js	3003	sansa.isutech.co.za
SANSA Backend	/var/www/sansa-backend/	Node.js + Express	8003	sansa.isutech.co.za/api
AssessFlow	/var/www/assess-flow/	Web application	Various	assess-flow.isutech.co.za
ConformEdge	/var/www/conformedge/	Web application	Various	conformedge.isutech.co.za
DealVault	/var/www/dealvault/	Web application	Various	dealvault.isutech.co.za
PropertyData Engine	/var/www/propertydata-engine/	Data processing engine	Various	propertydata-engine.isutech.co.za
Tumi Frontend	/var/www/tumi-frontend/	Frontend application	Various	tumi.isutech.co.za
Tumi Backend	/var/www/tumi-backend/	Backend API	Various	tumi.isutech.co.za/api
BuildQ	/var/www/buildq/	Construction platform	Various	buildq.isutech.co.za
Umdoni	/var/www/umdoni/	Municipal website	Various	umdoni.gov.za
DocsHub	/var/www/docs/	MkDocs documentation site	5001 (API)	docs.isutech.co.za

/opt/ Projects (Containerized)

Project	Location	Type	Docker Ports	Domain
Polelo DMS	/opt/polelo-dms/	Laravel + Nextcloud + PostgreSQL + Redis + Meilisearch	8100 (nginx), 8180 (nextcloud)	polelodms.isutech.co.za
AutoSlip	/opt/AutoSlip/	Containerized application	Various	autoslip.isutech.co.za
Buka	/opt/buka/	Containerized application	Various	buka.isutech.co.za

---

Polelo DMS Case Study

Polelo DMS is a perfect example of why containerized apps live in /opt/:

Architecture

┌─────────────────────────────────────────┐
│          Polelo DMS (Laravel)           │  Custom business logic
│  Workflows, File Plans, Audit, Reports  │
├─────────────────────────────────────────┤
│            Nextcloud                     │  Document storage, sync, mobile
│  Storage, Sync, Versioning, Sharing     │
├─────────────────────────────────────────┤
│  PostgreSQL + Redis + Meilisearch       │  Data layer
└─────────────────────────────────────────┘

Running Containers

polelo-nginx        # Nginx web server (port 8100)
polelo-app          # Laravel PHP application
polelo-nextcloud    # Nextcloud platform (port 8180)
polelo-meilisearch  # Search engine
polelo-redis        # Cache/queue

How It’s Accessed

1. Docker containers run at /opt/polelo-dms/
2. Nginx container exposes port 8100 internally
3. Host Nginx proxies polelodms.isutech.co.za → http://127.0.0.1:8100
4. SSL certificate managed by Let’s Encrypt on the host

---

Useful Commands for Server Exploration

Finding Projects

# List all projects in /var/www/
ls -la /var/www/

# List all containerized apps in /opt/
ls -la /opt/

# Find a specific project by name
find /var/www /opt -maxdepth 2 -type d -iname "*project-name*" 2>/dev/null

Checking Running Services

# List all systemd services
systemctl list-units --type=service

# Check services for a specific project
systemctl list-units --type=service | grep -i project-name

# Check status of a specific service
systemctl status service-name

Docker Operations

# List all running Docker containers
docker ps

# List all containers (including stopped)
docker ps -a

# Check containers for a specific project
docker ps | grep project-name

# View Docker Compose services for a project
cd /opt/project-name
docker compose ps

# View logs for a container
docker logs container-name

# Follow logs in real-time
docker logs -f container-name

Nginx Configuration

# List all enabled sites
ls /etc/nginx/sites-enabled/

# Search for a domain in nginx configs
grep -r "domain.com" /etc/nginx/sites-enabled/

# Test nginx configuration
nginx -t

# Reload nginx (after config changes)
systemctl reload nginx

Port Usage

# Check what's listening on all ports
ss -tulpn

# Check a specific port
ss -tulpn | grep :8100

# Find process using a port
lsof -i :8100

Project Exploration

# Check project structure
ls -la /var/www/project-name/
ls -la /opt/project-name/

# Look for configuration files
ls /var/www/project-name/{.env,config/,*.yml,*.json} 2>/dev/null

# Check if project uses Docker
ls /opt/project-name/docker-compose*.yml 2>/dev/null

# View package.json for Node.js projects
cat /var/www/project-name/package.json

# View requirements.txt for Python projects
cat /var/www/project-name/requirements.txt

# View composer.json for PHP projects
cat /var/www/project-name/composer.json

Process Management

# Check PM2 processes (Node.js apps)
pm2 list
pm2 info app-name
pm2 logs app-name

# Check systemd service logs
journalctl -u service-name -n 100 --no-pager

# Follow service logs
journalctl -u service-name -f

Database Connections

# Connect to PostgreSQL
psql -U username -d database_name

# List all PostgreSQL databases
psql -U postgres -c "\l"

# Connect to Redis
redis-cli

# Check Redis info
redis-cli info

---

Quick Reference Table

Task	/var/www/ Project	/opt/ Project
View logs	journalctl -u service-name -f or pm2 logs app-name	docker logs -f container-name
Restart	systemctl restart service-name or pm2 restart app-name	docker compose restart
Check status	systemctl status service-name or pm2 status	docker compose ps
View config	.env, config/ folder	docker-compose.yml, .env
Update code	git pull, restart service	git pull, docker compose up -d --build

---

Best Practices

For New Deployments

1. Decide on deployment type first:

   • Self-contained with multiple services? → Use Docker in /opt/
   • Traditional web app using host services? → Use /var/www/

2. Follow naming conventions:

   • Use lowercase with hyphens: project-name
   • Be consistent with domain names

3. Document your deployment:

   • Add to this inventory
   • Update nginx configs
   • Configure monitoring

For Maintenance

1. Always check the location first:

   find /var/www /opt -name "project-name" -type d

2. Understand the deployment type:

   • Check for docker-compose.yml → Containerized
   • Check for systemd service → Direct deployment

3. Use appropriate commands:

   • Don’t try to use systemctl on Docker containers
   • Don’t try to use docker commands on systemd services

---

Troubleshooting

”Where is this project?"

# Search everywhere
find /var/www /opt /home -name "*project*" -type d 2>/dev/null

"How is this project running?"

# Check systemd
systemctl list-units | grep -i project

# Check Docker
docker ps | grep -i project

# Check PM2
pm2 list | grep -i project

# Check ports
ss -tulpn | grep -i project

"Which domain points to this project?”

# Search nginx configs
grep -r "project-name\|domain.com" /etc/nginx/sites-enabled/

---

Additional Resources

• Hetzner Server Guide - Complete server management guide
• Monitoring Quick Reference - Server monitoring commands
• Development Workflow - Development process guidelines

---

Questions or Updates? If you discover new patterns or projects, please update this document to keep it current for the team.