​
Projects

A LocalCloud project is a self-contained development environment with its own configuration, services, and data. Each project is independent and can have different services and settings.

​
Project Structure

When you initialize a LocalCloud project, it creates the following structure: 
my-project/
├── .localcloud/
│   ├── config.yaml           # Project configuration
│   ├── logs/                 # Service logs (created on start)
│   │   ├── ollama.log
│   │   ├── postgres.log
│   │   ├── redis.log
│   │   └── minio.log
│   └── storage-credentials.json  # MinIO credentials (auto-generated)
├── .gitignore               # Git ignore rules
└── [your application files]
The .localcloud directory contains all LocalCloud-specific files. Your application code lives alongside it.

​
Configuration File

The heart of a LocalCloud project is the config.yaml file: 
# .localcloud/config.yaml
project:
  name: my-ai-app
  type: custom
  version: 1.0.0

services:
  ai:
    type: ollama
    port: 11434
    models:
      - llama2
      - mistral

  database:
    type: postgres
    version: "16"
    port: 5432
    name: localcloud
    user: localcloud
    password: auto-generated-password
    extensions:
      - pgvector
      - pg_trgm

  cache:
    type: redis
    version: "7"
    port: 6379

  queue:
    type: redis  # Shares instance with cache
    port: 6379

  storage:
    type: minio
    port: 9000
    console: 9001

resources:
  memory_limit: "4Gi"
  cpu_limit: "2"

components:
  - llm
  - embedding
  - database
  - cache
  - storage

connectivity:
  tunnel:
    enabled: false
    provider: ngrok

​
Project Types

LocalCloud supports different project types with optimized defaults:
Default type - You choose exactly what services to include
project:
type: custom
Best for: Specific requirements, minimal setups

​
Project Lifecycle

​
1. Initialization

lc init my-project
Creates project structure and default configuration.

​
2. Setup

lc setup
Interactive wizard to:
  • Select project type
  • Choose components
  • Pick AI models
  • Configure services

​
3. Development

lc start  # Start services
lc status # Check status
lc logs   # View logs
lc stop   # Stop services

​
4. Reset/Cleanup

lc reset        # Soft reset (keep data)
lc reset --hard # Remove everything

​
Component System

Components are logical groupings of functionality:

​
Port Management

LocalCloud automatically manages ports to avoid conflicts:

​
Default Ports

  • Ollama: 11434
  • PostgreSQL: 5432
  • Redis: 6379
  • MinIO API: 9000
  • MinIO Console: 9001

​
Port Allocation

If default ports are in use, LocalCloud will:
  1. Detect the conflict
  2. Find an available port
  3. Update configuration
  4. Show the new port in lc status
You can manually set ports in config.yaml if needed.

​
Data Management

​
Data Persistence

Project data is stored in Docker volumes: 
# List volumes for current project
docker volume ls | grep localcloud

# Example output:
localcloud_my-ai-app_postgres_data
localcloud_my-ai-app_redis_data
localcloud_my-ai-app_ollama_models
localcloud_my-ai-app_minio_data

​
Backup and Restore

# Backup PostgreSQL
docker exec localcloud-postgres pg_dump -U localcloud localcloud > backup.sql

# Backup MinIO data
docker run --rm \
-v localcloud_minio_data:/data \
-v $(pwd):/backup \
alpine tar czf /backup/minio-backup.tar.gz /data

​
Multiple Projects

You can have multiple LocalCloud projects: 
# Project 1
cd ~/projects/chat-app
lc init
lc start

# Project 2 (different directory)
cd ~/projects/rag-system
lc init
lc start --project .
Services from different projects may conflict if using the same ports. LocalCloud will detect and handle this automatically.

​
Environment Variables

LocalCloud sets environment variables for service discovery: 
# Automatically set when services start
LOCALCLOUD_AI_URL=http://localhost:11434
LOCALCLOUD_DB_URL=postgresql://localcloud:localcloud@localhost:5432/localcloud
LOCALCLOUD_REDIS_URL=redis://localhost:6379
LOCALCLOUD_MINIO_URL=http://localhost:9000
Use in your application: 
import os

ai_url = os.getenv('LOCALCLOUD_AI_URL', 'http://localhost:11434')
db_url = os.getenv('LOCALCLOUD_DB_URL')

​
Project Templates

Create projects from templates: 
# Interactive template selection
lc setup chat

# With options
lc setup api --name my-api --port 8080
Templates include:
  • Pre-configured services
  • Example code
  • Best practices
  • Documentation

​
Version Control

# LocalCloud
.localcloud/data/
.localcloud/logs/
.localcloud/tunnels/
.localcloud/storage-credentials.json

# Keep config
!.localcloud/config.yaml

# Environment
.env
.env.local

# OS
.DS_Store
Thumbs.db

​
Sharing Projects

To share a LocalCloud project:
  1. Commit .localcloud/config.yaml
  2. Document required models in README
  3. Other developers run:
git clone <project>
cd <project>
lc start  # Auto-downloads everything

​
Troubleshooting

​
Best Practices

  1. One project per application - Keep projects isolated
  2. Commit config.yaml - Share configuration with team
  3. Use components - Logical grouping over individual services
  4. Document models - List required AI models in README
  5. Regular backups - Backup data before major changes

​
Next Steps

Configuration

Deep dive into configuration

CLI Commands

Master project management

Services

Understand available services

Quick Start

Create your first project