From 3ee371c287f682fe79b486a7c56d2fc1d7ccee72 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 14 Nov 2025 13:54:06 +0000
Subject: [PATCH 1/2] Initial plan


From 5757ede32d03fa63c78a1e0025d0ea72e89e8940 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 14 Nov 2025 14:04:05 +0000
Subject: [PATCH 2/2] docs: add comprehensive first batch of documentation

Co-authored-by: undefinedhuman <56697016+undefinedhuman@users.noreply.github.com>
---
 .../docs/1.getting-started/1.introduction.md  |  85 +++-
 .../docs/1.getting-started/2.installation.md  | 245 +++++++++++
 .../docs/1.getting-started/3.quick-start.md   | 220 ++++++++++
 content/docs/3.core-concepts/1.overview.md    | 213 +++++++++
 content/docs/4.guides/1.configuration.md      | 411 ++++++++++++++++++
 nuxt.config.ts                                |   4 +
 6 files changed, 1173 insertions(+), 5 deletions(-)
 create mode 100644 content/docs/1.getting-started/2.installation.md
 create mode 100644 content/docs/1.getting-started/3.quick-start.md
 create mode 100644 content/docs/3.core-concepts/1.overview.md
 create mode 100644 content/docs/4.guides/1.configuration.md

diff --git a/content/docs/1.getting-started/1.introduction.md b/content/docs/1.getting-started/1.introduction.md
index 133d921..4a0150f 100644
--- a/content/docs/1.getting-started/1.introduction.md
+++ b/content/docs/1.getting-started/1.introduction.md
@@ -1,10 +1,85 @@
 ---
 title: "Introduction"
-description: ""
+description: "Welcome to Cosmify - A self-hosted Platform as a Service (PaaS) solution"
 ---
 
-Coming soon!
+# Introduction
 
-```typescript [intro.ts]
-Hello, world!
-```
\ No newline at end of file
+Welcome to **Cosmify**, a powerful self-hosted Platform as a Service (PaaS) that gives you complete control over your infrastructure without vendor lock-in.
+
+## What is Cosmify?
+
+Cosmify is an open-source platform that enables you to deploy, manage, and scale applications on your own infrastructure. Think of it as your own Heroku or Platform.sh, but running on servers you control.
+
+## Key Features
+
+### 🚀 Self-Hosted Deployment
+Deploy applications and manage infrastructure effortlessly on your own servers or cloud provider of choice.
+
+### ☁️ Multi-Cloud Support
+Works seamlessly with various cloud providers (AWS, DigitalOcean, Hetzner, etc.) or self-hosted environments.
+
+### 🎨 User-Friendly UI
+A clean and intuitive dashboard built with Vue.js for better usability and management.
+
+### 🐳 Docker-Based
+Leverages Docker for containerized deployments, ensuring consistency across environments.
+
+### 🔐 Secure by Design
+Built-in security measures including authentication, authorization, and isolated environments.
+
+### 📊 Organization Management
+Multi-tenancy support with organizations, projects, and role-based access control.
+
+## Core Capabilities
+
+Cosmify currently provides:
+
+- **Project Management**: Organize your applications into projects
+- **Container Orchestration**: Deploy and manage Docker containers
+- **Network Management**: Configure virtual networks for your applications
+- **Server Management**: Connect and manage multiple servers
+- **Environment Variables**: Secure configuration management
+- **Port Mapping**: Expose your applications to the internet
+
+## Coming Soon
+
+Cosmify is actively being developed. Upcoming features include:
+
+- **Database Management**: Deploy and manage PostgreSQL, MySQL, Redis, and more
+- **Automated Deployments**: Git-based workflows with GitHub and GitLab integration
+- **Advanced Monitoring**: Built-in metrics, logging, and alerting
+- **Load Balancing**: Distribute traffic across multiple instances
+- **Backup & Recovery**: Automated backups for databases and volumes
+
+## Why Choose Cosmify?
+
+- **No Vendor Lock-In**: Your infrastructure, your rules
+- **Cost Effective**: Pay only for your infrastructure costs
+- **Full Control**: Complete access to your data and configurations
+- **Open Source**: Transparent, auditable, and community-driven
+- **Privacy First**: Your data stays on your infrastructure
+
+## Who is Cosmify For?
+
+Cosmify is ideal for:
+
+- **Startups** looking for a cost-effective PaaS alternative
+- **Development Teams** wanting control over their deployment pipeline
+- **Agencies** managing multiple client applications
+- **Enterprises** requiring on-premises or private cloud deployments
+- **Developers** who want to learn about PaaS architecture
+
+## Architecture
+
+Cosmify consists of three main components:
+
+1. **Backend API**: Express.js REST API handling all business logic
+2. **Frontend Dashboard**: Vue.js web application for management
+3. **PostgreSQL Database**: Stores all configuration and metadata
+
+The platform communicates with your servers via SSH to manage Docker containers and orchestrate deployments.
+
+## Next Steps
+
+Ready to get started? Head over to the [Installation](/docs/getting-started/installation) guide to set up Cosmify on your infrastructure.
\ No newline at end of file
diff --git a/content/docs/1.getting-started/2.installation.md b/content/docs/1.getting-started/2.installation.md
new file mode 100644
index 0000000..a422750
--- /dev/null
+++ b/content/docs/1.getting-started/2.installation.md
@@ -0,0 +1,245 @@
+---
+title: "Installation"
+description: "Learn how to install and set up Cosmify on your infrastructure"
+---
+
+# Installation
+
+This guide walks you through installing Cosmify on your infrastructure. Cosmify can be installed on a single server or distributed across multiple servers.
+
+## Prerequisites
+
+Before installing Cosmify, ensure you have:
+
+- A server with **Ubuntu 20.04+** or **Debian 11+** (other Linux distributions may work but are untested)
+- At least **2GB RAM** and **20GB disk space**
+- **Docker** and **Docker Compose** installed
+- **PostgreSQL 13+** (can be installed via Docker)
+- **Node.js 18+** and **Yarn** (for building from source)
+- **SSH access** with sudo privileges
+
+## System Requirements
+
+### Minimum Requirements
+- **CPU**: 2 cores
+- **RAM**: 2GB
+- **Storage**: 20GB
+- **OS**: Ubuntu 20.04+ or Debian 11+
+
+### Recommended Requirements
+- **CPU**: 4 cores
+- **RAM**: 4GB
+- **Storage**: 50GB SSD
+- **OS**: Ubuntu 22.04 LTS
+
+## Installation Methods
+
+### Method 1: Docker Compose (Recommended)
+
+The easiest way to get started with Cosmify is using Docker Compose.
+
+#### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/cosmify-dev/cosmify.git
+cd cosmify
+```
+
+#### Step 2: Configure Environment Variables
+
+Create a `.env` file in the root directory:
+
+```bash
+cp .env.example .env
+```
+
+Edit the `.env` file with your configuration:
+
+```bash
+# Database Configuration
+POSTGRES_HOST=database
+POSTGRES_PORT=5432
+POSTGRES_USER=admin
+POSTGRES_PASSWORD=your_secure_password_here
+POSTGRES_DB=cosmify
+
+# Backend Configuration
+BACKEND_PORT=3001
+NODE_ENV=production
+
+# Frontend Configuration
+VITE_API_URL=http://localhost:3001
+
+# Security
+JWT_SECRET=your_jwt_secret_here
+SESSION_SECRET=your_session_secret_here
+```
+
+#### Step 3: Start Services
+
+Start the development environment:
+
+```bash
+docker-compose -f infra/docker-compose.dev.yml up -d
+```
+
+Or for production:
+
+```bash
+docker-compose up -d
+```
+
+#### Step 4: Access Cosmify
+
+Open your browser and navigate to:
+- **Frontend**: `http://localhost:3000`
+- **Backend API**: `http://localhost:3001`
+
+### Method 2: Manual Installation
+
+For more control, you can install Cosmify manually.
+
+#### Step 1: Install Dependencies
+
+```bash
+# Update system packages
+sudo apt update && sudo apt upgrade -y
+
+# Install Node.js 18
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Install Yarn
+npm install -g yarn
+
+# Install Docker
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+sudo usermod -aG docker $USER
+
+# Install PostgreSQL
+sudo apt install -y postgresql postgresql-contrib
+```
+
+#### Step 2: Set Up Database
+
+```bash
+# Create database and user
+sudo -u postgres psql <<EOF
+CREATE DATABASE cosmify;
+CREATE USER cosmify WITH ENCRYPTED PASSWORD 'your_password';
+GRANT ALL PRIVILEGES ON DATABASE cosmify TO cosmify;
+EOF
+```
+
+#### Step 3: Clone and Build
+
+```bash
+# Clone repository
+git clone https://github.com/cosmify-dev/cosmify.git
+cd cosmify
+
+# Install dependencies
+yarn install
+
+# Build backend
+yarn nx build backend
+
+# Build frontend
+yarn nx build frontend
+```
+
+#### Step 4: Configure Environment
+
+Create environment files for both backend and frontend as described in Method 1.
+
+#### Step 5: Start Services
+
+```bash
+# Start backend
+yarn nx serve backend
+
+# In another terminal, start frontend
+yarn nx serve frontend
+```
+
+## Post-Installation
+
+### Create Admin Account
+
+After installation, create your first admin account by registering through the web interface at `http://localhost:3000`.
+
+### Configure SSH Keys
+
+To manage remote servers, you'll need to configure SSH access:
+
+1. Generate an SSH key pair:
+```bash
+ssh-keygen -t ed25519 -C "cosmify@yourserver"
+```
+
+2. Add the public key to your target servers:
+```bash
+ssh-copy-id user@your-server-ip
+```
+
+3. Add the private key to Cosmify through the UI in Settings → SSH Keys.
+
+## Firewall Configuration
+
+If you're using a firewall, ensure these ports are accessible:
+
+- **3000**: Frontend (HTTP)
+- **3001**: Backend API (HTTP)
+- **5432**: PostgreSQL (only if external access needed)
+- **22**: SSH (for server management)
+
+Example UFW rules:
+
+```bash
+sudo ufw allow 22/tcp
+sudo ufw allow 3000/tcp
+sudo ufw allow 3001/tcp
+sudo ufw enable
+```
+
+## Updating Cosmify
+
+To update to the latest version:
+
+```bash
+cd cosmify
+git pull origin main
+yarn install
+yarn nx build backend
+yarn nx build frontend
+```
+
+Then restart your services.
+
+## Troubleshooting
+
+### Database Connection Issues
+
+If you can't connect to the database:
+
+1. Check PostgreSQL is running: `sudo systemctl status postgresql`
+2. Verify connection details in `.env`
+3. Ensure PostgreSQL allows connections from your host
+
+### Docker Permission Errors
+
+If you get Docker permission errors:
+
+```bash
+sudo usermod -aG docker $USER
+newgrp docker
+```
+
+### Port Already in Use
+
+If ports 3000 or 3001 are in use, you can change them in your `.env` file.
+
+## Next Steps
+
+Now that Cosmify is installed, proceed to the [Quick Start](/docs/getting-started/quick-start) guide to deploy your first application.
diff --git a/content/docs/1.getting-started/3.quick-start.md b/content/docs/1.getting-started/3.quick-start.md
new file mode 100644
index 0000000..df3673a
--- /dev/null
+++ b/content/docs/1.getting-started/3.quick-start.md
@@ -0,0 +1,220 @@
+---
+title: "Quick Start"
+description: "Deploy your first application with Cosmify in minutes"
+---
+
+# Quick Start
+
+This guide will help you deploy your first application on Cosmify. We'll walk through creating an organization, adding a server, and deploying a simple web application.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- ✅ Cosmify installed and running (see [Installation](/docs/getting-started/installation))
+- ✅ A registered account on your Cosmify instance
+- ✅ A server with Docker installed (can be the same server running Cosmify)
+- ✅ SSH access to your target server
+
+## Step 1: Create an Organization
+
+Organizations help you organize projects and manage team access.
+
+1. Log in to your Cosmify dashboard
+2. Click **"Create Organization"** on the home page
+3. Enter your organization details:
+   - **Name**: My First Organization
+   - **Description**: Optional description
+4. Click **"Create"**
+
+## Step 2: Add a Server
+
+Servers are the compute resources where your applications will run.
+
+1. Navigate to **Servers** in the sidebar
+2. Click **"Add Server"**
+3. Fill in the server details:
+   - **Name**: Production Server
+   - **Host**: Your server's IP address or hostname
+   - **Port**: 22 (default SSH port)
+   - **Username**: Your SSH username (e.g., `root` or `ubuntu`)
+   - **SSH Key**: Select or add your SSH private key
+4. Click **"Test Connection"** to verify SSH access
+5. Click **"Add Server"**
+
+Cosmify will now connect to your server and verify Docker is installed.
+
+## Step 3: Create a Project
+
+Projects group related applications and services together.
+
+1. Click **"Projects"** in the sidebar
+2. Click **"Create Project"**
+3. Enter project details:
+   - **Name**: My Web App
+   - **Organization**: Select your organization
+   - **Description**: My first application on Cosmify
+4. Click **"Create"**
+
+## Step 4: Deploy a Container
+
+Let's deploy a simple Nginx web server as your first application.
+
+1. Open your project
+2. Click **"Deploy Container"**
+3. Configure the container:
+   - **Name**: web-server
+   - **Image**: nginx:latest
+   - **Server**: Select your server
+   - **Port Mapping**: Add port mapping
+     - **Container Port**: 80
+     - **Host Port**: 8080
+4. Click **"Deploy"**
+
+Cosmify will now:
+- Pull the Nginx image on your server
+- Create and start the container
+- Configure port mapping
+
+## Step 5: Verify Deployment
+
+1. Once deployed, you'll see the container status change to **"Running"**
+2. Navigate to **Containers** to see your deployed containers
+3. Click on your container to view details, logs, and metrics
+4. Open your browser and visit: `http://your-server-ip:8080`
+
+You should see the Nginx welcome page! 🎉
+
+## Step 6: Configure Environment Variables (Optional)
+
+Many applications require environment variables for configuration.
+
+1. Open your container details
+2. Click **"Environment Variables"**
+3. Add variables:
+   - **Key**: `MY_VARIABLE`
+   - **Value**: `my-value`
+4. Click **"Save"**
+5. Restart the container for changes to take effect
+
+## Step 7: Manage Your Container
+
+From the container details page, you can:
+
+- **View Logs**: Real-time container logs
+- **Restart**: Restart the container
+- **Stop**: Stop the container
+- **Remove**: Delete the container
+- **Update**: Update container configuration
+
+## Common Deployment Scenarios
+
+### Deploy a Node.js Application
+
+```yaml
+Name: my-node-app
+Image: node:18-alpine
+Working Directory: /app
+Command: node server.js
+Port Mapping:
+  - Container: 3000
+  - Host: 3000
+Environment Variables:
+  - NODE_ENV=production
+  - PORT=3000
+```
+
+### Deploy a Database (PostgreSQL)
+
+```yaml
+Name: postgres-db
+Image: postgres:15
+Port Mapping:
+  - Container: 5432
+  - Host: 5432
+Environment Variables:
+  - POSTGRES_USER=myapp
+  - POSTGRES_PASSWORD=secure_password
+  - POSTGRES_DB=myapp_db
+Volumes:
+  - /var/lib/postgresql/data
+```
+
+### Deploy a Custom Application
+
+```yaml
+Name: my-custom-app
+Image: myregistry.com/my-app:latest
+Port Mapping:
+  - Container: 8000
+  - Host: 8000
+Environment Variables:
+  - DATABASE_URL=postgresql://user:pass@db:5432/mydb
+  - REDIS_URL=redis://redis:6379
+Network: my-app-network
+```
+
+## Using Docker Compose (Coming Soon)
+
+Cosmify will soon support deploying multi-container applications using Docker Compose files:
+
+```yaml
+version: '3.8'
+services:
+  web:
+    image: nginx:latest
+    ports:
+      - "80:80"
+  app:
+    image: node:18
+    environment:
+      - NODE_ENV=production
+    depends_on:
+      - db
+  db:
+    image: postgres:15
+    environment:
+      - POSTGRES_PASSWORD=secret
+```
+
+## Troubleshooting
+
+### Container Won't Start
+
+- Check the container logs for error messages
+- Verify the Docker image exists and can be pulled
+- Ensure port mappings don't conflict with existing services
+- Check environment variables are correctly set
+
+### Can't Access Application
+
+- Verify the container is running
+- Check port mappings are correct
+- Ensure firewall allows traffic on the mapped port
+- Confirm the application is listening on `0.0.0.0` not `localhost`
+
+### SSH Connection Failed
+
+- Verify SSH credentials are correct
+- Check the server is accessible from Cosmify
+- Ensure SSH key has proper permissions (600)
+- Verify Docker is installed on the target server
+
+## Next Steps
+
+Congratulations! You've deployed your first application on Cosmify. 
+
+Here's what to explore next:
+
+- [Core Concepts](/docs/core-concepts/overview) - Understanding Cosmify's architecture
+- [Configuration](/docs/guides/configuration) - Advanced configuration options
+- [Networking](/docs/guides/networking) - Setting up virtual networks
+- [Security](/docs/guides/security) - Securing your deployments
+
+## Getting Help
+
+If you run into issues:
+
+- Check the [Troubleshooting](#troubleshooting) section above
+- Visit our [Community](/docs/community/contribute-docs) page
+- Report bugs on [GitHub Issues](https://github.com/cosmify-dev/cosmify/issues)
diff --git a/content/docs/3.core-concepts/1.overview.md b/content/docs/3.core-concepts/1.overview.md
new file mode 100644
index 0000000..5f29073
--- /dev/null
+++ b/content/docs/3.core-concepts/1.overview.md
@@ -0,0 +1,213 @@
+---
+title: "Overview"
+description: "Understanding Cosmify's core concepts and architecture"
+---
+
+# Core Concepts
+
+This guide introduces the fundamental concepts you need to understand to effectively use Cosmify.
+
+## Architecture Overview
+
+Cosmify follows a client-server architecture with three main layers:
+
+```
+┌─────────────────────────────────────────────┐
+│          Frontend Dashboard (Vue.js)        │
+│              (Port 3000)                    │
+└──────────────────┬──────────────────────────┘
+                   │ HTTP/REST
+┌──────────────────▼──────────────────────────┐
+│          Backend API (Express.js)           │
+│              (Port 3001)                    │
+└──────────────────┬──────────────────────────┘
+                   │ TypeORM
+┌──────────────────▼──────────────────────────┐
+│      PostgreSQL Database (Port 5432)        │
+└──────────────────┬──────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────┐
+│        Managed Servers (via SSH)            │
+│          Running Docker Containers          │
+└─────────────────────────────────────────────┘
+```
+
+## Key Components
+
+### 1. Organizations
+
+Organizations are the top-level entity in Cosmify's hierarchy. They provide:
+
+- **Multi-tenancy**: Separate different teams or clients
+- **Resource isolation**: Each organization has its own projects and resources
+- **Access control**: Manage team members and their permissions
+- **Billing boundaries**: (Coming soon) Separate billing per organization
+
+**Example Use Cases:**
+- One organization per company
+- One organization per client (for agencies)
+- Separate organizations for development and production
+
+### 2. Projects
+
+Projects group related applications and services together. They provide:
+
+- **Logical grouping**: Keep related containers organized
+- **Environment separation**: dev, staging, production projects
+- **Resource sharing**: Share networks and volumes within a project
+- **Team collaboration**: Assign team members to specific projects
+
+**Best Practices:**
+- Create separate projects for different applications
+- Use naming conventions: `app-name-environment` (e.g., `website-production`)
+- Group microservices of the same application in one project
+
+### 3. Servers
+
+Servers are the physical or virtual machines where your containers run. They:
+
+- **Host containers**: Execute your Docker containers
+- **Provide resources**: CPU, memory, and storage
+- **Network connectivity**: Enable container communication
+- **Remote management**: Managed via SSH from Cosmify
+
+**Server Types:**
+- **Cloud VPS**: DigitalOcean, AWS EC2, Linode, etc.
+- **Bare metal**: Physical servers in your datacenter
+- **Local**: Development machines
+
+**Server Requirements:**
+- Linux OS (Ubuntu 20.04+ recommended)
+- Docker installed
+- SSH access
+- Sufficient resources for your workloads
+
+### 4. Containers
+
+Containers are the running instances of your applications. They:
+
+- **Run from Docker images**: Pull from Docker Hub or private registries
+- **Isolated execution**: Each container runs independently
+- **Configurable resources**: Set CPU and memory limits
+- **Port mapping**: Expose services to the network
+- **Environment variables**: Runtime configuration
+
+**Container Lifecycle:**
+```
+Created → Starting → Running → Stopping → Stopped → Removed
+```
+
+### 5. Networks
+
+Networks enable communication between containers. They provide:
+
+- **Container isolation**: Separate network namespaces
+- **Service discovery**: Containers can communicate by name
+- **Security**: Control which containers can communicate
+- **Bridge mode**: Default Docker networking
+
+**Network Types:**
+- **Bridge**: Default, isolated network
+- **Host**: Share host's network stack
+- **Overlay**: Multi-host networking (coming soon)
+
+### 6. Volumes
+
+Volumes provide persistent storage for containers. They:
+
+- **Persist data**: Survive container restarts and deletions
+- **Share data**: Multiple containers can mount the same volume
+- **Backup**: Can be backed up independently
+- **Performance**: Better performance than bind mounts
+
+**Common Uses:**
+- Database data directories
+- Application uploads and media
+- Configuration files
+- Logs
+
+### 7. Environment Variables
+
+Environment variables configure container behavior. They:
+
+- **Runtime configuration**: Set without rebuilding images
+- **Secrets management**: Store API keys and passwords
+- **Feature flags**: Enable/disable features
+- **Service URLs**: Database connections, API endpoints
+
+**Best Practices:**
+- Never commit secrets to version control
+- Use descriptive names: `DATABASE_URL`, not `DB`
+- Group related variables with prefixes: `REDIS_HOST`, `REDIS_PORT`
+
+### 8. Ports
+
+Ports expose container services to the network. They:
+
+- **Map container to host**: Container:80 → Host:8080
+- **Enable access**: Make services accessible
+- **Load balancing**: (Coming soon) Distribute traffic
+
+**Port Types:**
+- **Container Port**: Port the application listens on inside the container
+- **Host Port**: Port exposed on the server
+- **Public Port**: Port accessible from the internet
+
+## Resource Hierarchy
+
+Understanding the resource hierarchy helps organize your infrastructure:
+
+```
+Organization
+├── Projects
+│   ├── Containers
+│   │   ├── Environment Variables
+│   │   ├── Port Mappings
+│   │   └── Volumes
+│   └── Networks
+└── Servers
+    ├── Docker Engine
+    └── System Resources
+```
+
+## Data Flow
+
+Here's how a typical deployment works:
+
+1. **User Action**: User clicks "Deploy Container" in the dashboard
+2. **API Request**: Frontend sends request to backend API
+3. **Authentication**: Backend verifies user permissions
+4. **Database Update**: Container configuration saved to PostgreSQL
+5. **SSH Connection**: Backend connects to target server via SSH
+6. **Docker Command**: Executes `docker run` with configuration
+7. **Status Update**: Container status synced back to database
+8. **UI Update**: Dashboard reflects new container state
+
+## Security Model
+
+Cosmify implements security at multiple levels:
+
+- **Authentication**: User login with Better Auth
+- **Authorization**: Role-based access control (RBAC)
+- **Encryption**: HTTPS for web traffic, SSH for server communication
+- **Isolation**: Containers run in isolated namespaces
+- **Secrets**: Encrypted storage of sensitive data
+
+## State Management
+
+Cosmify maintains state in PostgreSQL:
+
+- **Configuration**: Container definitions, environment variables
+- **Metadata**: Project names, descriptions, timestamps
+- **Relationships**: Organization → Project → Container hierarchy
+- **User data**: Accounts, permissions, SSH keys
+
+The actual container state lives on the Docker hosts, and Cosmify periodically syncs state.
+
+## Next Steps
+
+Now that you understand the core concepts, explore:
+
+- [Architecture Deep Dive](/docs/core-concepts/architecture) - Detailed technical architecture
+- [Configuration Guide](/docs/guides/configuration) - Configure Cosmify components
+- [Deployment Guide](/docs/guides/deployment) - Deploy production workloads
diff --git a/content/docs/4.guides/1.configuration.md b/content/docs/4.guides/1.configuration.md
new file mode 100644
index 0000000..5022f3d
--- /dev/null
+++ b/content/docs/4.guides/1.configuration.md
@@ -0,0 +1,411 @@
+---
+title: "Configuration"
+description: "Configure Cosmify for your environment"
+---
+
+# Configuration
+
+This guide covers how to configure Cosmify for different environments and use cases.
+
+## Environment Variables
+
+Cosmify uses environment variables for configuration. These are typically set in a `.env` file.
+
+### Backend Configuration
+
+#### Database Settings
+
+```bash
+# PostgreSQL connection
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=cosmify
+POSTGRES_PASSWORD=your_secure_password
+POSTGRES_DB=cosmify
+
+# Database pool settings (optional)
+POSTGRES_POOL_MIN=2
+POSTGRES_POOL_MAX=10
+```
+
+#### Server Settings
+
+```bash
+# Backend API server
+BACKEND_PORT=3001
+BACKEND_HOST=0.0.0.0
+
+# Node environment
+NODE_ENV=production
+```
+
+#### Authentication
+
+```bash
+# JWT configuration
+JWT_SECRET=your_jwt_secret_minimum_32_characters
+JWT_EXPIRATION=7d
+
+# Session configuration
+SESSION_SECRET=your_session_secret_minimum_32_characters
+SESSION_DURATION=24h
+```
+
+#### Security
+
+```bash
+# CORS settings
+CORS_ORIGIN=http://localhost:3000
+CORS_CREDENTIALS=true
+
+# Rate limiting
+RATE_LIMIT_WINDOW=15m
+RATE_LIMIT_MAX=100
+```
+
+### Frontend Configuration
+
+```bash
+# API endpoint
+VITE_API_URL=http://localhost:3001
+
+# Application settings
+VITE_APP_NAME=Cosmify
+VITE_APP_URL=http://localhost:3000
+```
+
+### Email Configuration (Optional)
+
+For email notifications and password resets:
+
+```bash
+# SMTP settings
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=your-email@gmail.com
+SMTP_PASSWORD=your-app-password
+SMTP_FROM=noreply@cosmify.dev
+```
+
+## Configuration Files
+
+### Docker Compose
+
+For Docker-based deployments, configure `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  database:
+    image: postgres:15
+    restart: always
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    ports:
+      - "5432:5432"
+
+  backend:
+    build:
+      context: .
+      dockerfile: apps/backend/Dockerfile
+    restart: always
+    depends_on:
+      - database
+    environment:
+      POSTGRES_HOST: database
+      POSTGRES_PORT: 5432
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+      JWT_SECRET: ${JWT_SECRET}
+      SESSION_SECRET: ${SESSION_SECRET}
+    ports:
+      - "3001:3001"
+
+  frontend:
+    build:
+      context: .
+      dockerfile: apps/frontend/Dockerfile
+    restart: always
+    depends_on:
+      - backend
+    environment:
+      VITE_API_URL: http://backend:3001
+    ports:
+      - "3000:3000"
+
+volumes:
+  postgres_data:
+```
+
+### Nginx Reverse Proxy
+
+For production deployments, use Nginx as a reverse proxy:
+
+```nginx
+# /etc/nginx/sites-available/cosmify
+
+upstream backend {
+    server localhost:3001;
+}
+
+upstream frontend {
+    server localhost:3000;
+}
+
+server {
+    listen 80;
+    server_name cosmify.example.com;
+
+    # Redirect to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name cosmify.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/cosmify.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/cosmify.example.com/privkey.pem;
+
+    # Frontend
+    location / {
+        proxy_pass http://frontend;
+        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;
+    }
+
+    # Backend API
+    location /api {
+        proxy_pass http://backend;
+        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;
+    }
+
+    # WebSocket support (for future features)
+    location /ws {
+        proxy_pass http://backend;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+## Production Configuration
+
+### SSL/TLS Certificates
+
+Use Let's Encrypt for free SSL certificates:
+
+```bash
+# Install certbot
+sudo apt install certbot python3-certbot-nginx
+
+# Obtain certificate
+sudo certbot --nginx -d cosmify.example.com
+
+# Auto-renewal is configured by default
+sudo certbot renew --dry-run
+```
+
+### Database Backup
+
+Configure automated PostgreSQL backups:
+
+```bash
+#!/bin/bash
+# /usr/local/bin/backup-cosmify.sh
+
+BACKUP_DIR="/var/backups/cosmify"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+
+# Create backup
+pg_dump -U cosmify cosmify > "$BACKUP_DIR/cosmify_$TIMESTAMP.sql"
+
+# Compress backup
+gzip "$BACKUP_DIR/cosmify_$TIMESTAMP.sql"
+
+# Remove backups older than 30 days
+find "$BACKUP_DIR" -name "*.sql.gz" -mtime +30 -delete
+```
+
+Add to crontab:
+
+```bash
+# Daily backup at 2 AM
+0 2 * * * /usr/local/bin/backup-cosmify.sh
+```
+
+### Resource Limits
+
+Configure Docker resource limits in docker-compose.yml:
+
+```yaml
+services:
+  backend:
+    # ... other config
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 2G
+        reservations:
+          cpus: '1'
+          memory: 1G
+```
+
+### Logging
+
+Configure log rotation for Docker:
+
+```json
+{
+  "log-driver": "json-file",
+  "log-opts": {
+    "max-size": "10m",
+    "max-file": "3"
+  }
+}
+```
+
+Add to `/etc/docker/daemon.json` and restart Docker:
+
+```bash
+sudo systemctl restart docker
+```
+
+## Security Hardening
+
+### Firewall Configuration
+
+Configure UFW (Ubuntu Firewall):
+
+```bash
+# Allow SSH
+sudo ufw allow 22/tcp
+
+# Allow HTTP/HTTPS
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# Enable firewall
+sudo ufw enable
+```
+
+### SSH Hardening
+
+Update `/etc/ssh/sshd_config`:
+
+```
+# Disable root login
+PermitRootLogin no
+
+# Use SSH keys only
+PasswordAuthentication no
+PubkeyAuthentication yes
+
+# Disable empty passwords
+PermitEmptyPasswords no
+
+# Set login timeout
+LoginGraceTime 30
+```
+
+Restart SSH:
+
+```bash
+sudo systemctl restart sshd
+```
+
+### Database Security
+
+Secure PostgreSQL:
+
+```bash
+# Edit pg_hba.conf to restrict access
+sudo nano /etc/postgresql/15/main/pg_hba.conf
+
+# Only allow localhost connections
+local   all   all   peer
+host    all   all   127.0.0.1/32   scram-sha-256
+```
+
+## Environment-Specific Configuration
+
+### Development
+
+```bash
+NODE_ENV=development
+LOG_LEVEL=debug
+ENABLE_CORS=true
+CORS_ORIGIN=*
+```
+
+### Staging
+
+```bash
+NODE_ENV=staging
+LOG_LEVEL=info
+ENABLE_CORS=true
+CORS_ORIGIN=https://staging.cosmify.example.com
+```
+
+### Production
+
+```bash
+NODE_ENV=production
+LOG_LEVEL=warn
+ENABLE_CORS=true
+CORS_ORIGIN=https://cosmify.example.com
+RATE_LIMIT_ENABLED=true
+```
+
+## Monitoring Configuration
+
+### Health Checks
+
+Configure health check endpoints:
+
+```yaml
+services:
+  backend:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+```
+
+### Logging
+
+Configure Winston logger in backend:
+
+```javascript
+// Backend logging configuration
+const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' }),
+  ],
+});
+```
+
+## Next Steps
+
+- [Deployment Guide](/docs/guides/deployment) - Deploy to production
+- [Security Best Practices](/docs/guides/security) - Secure your installation
+- [Troubleshooting](/docs/guides/troubleshooting) - Common issues and solutions
diff --git a/nuxt.config.ts b/nuxt.config.ts
index a396595..50f56ea 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -60,7 +60,11 @@ export default defineNuxtConfig({
       routes: [
         "/sitemap.xml",
         "/",
+        "/docs/getting-started/introduction",
         "/docs/getting-started/installation",
+        "/docs/getting-started/quick-start",
+        "/docs/core-concepts/overview",
+        "/docs/guides/configuration",
         "/docs/community/contribute-docs",
       ],
     },