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:

Custom
Chat
RAG
API

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:

LLM Component

Language model for text generation

Service: Ollama
Models: Llama, Mistral, etc.
Use: Chat, completion, reasoning

Embedding Component

Convert text to vectors

Service: Ollama
Models: nomic-embed-text, mxbai-embed-large
Use: Semantic search, RAG

Database Component

Persistent data storage

Service: PostgreSQL
Extensions: pgvector for embeddings
Use: Application data, vector storage

Cache Component

High-speed data access

Service: Redis
Features: Caching, pub/sub
Use: Session storage, queues

Storage Component

File and object storage

Service: MinIO
Protocol: S3-compatible
Use: Documents, images, backups

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:

Detect the conflict
Find an available port
Update configuration
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

Recommended .gitignore

# 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

To share a LocalCloud project:

Commit .localcloud/config.yaml
Document required models in README
Other developers run:

git clone <project>
cd <project>
lc start  # Auto-downloads everything

Troubleshooting

Project already initialized

If you see “project already initialized”:

Check for existing .localcloud directory
Use lc reset --hard to start fresh
Or cd to the existing project

Configuration not found

If LocalCloud can’t find config:

Ensure you’re in project root
Check .localcloud/config.yaml exists
Run lc init if needed

Port conflicts

If services fail to start:

Check lc status for port info
Update ports in config.yaml
Or stop conflicting services

Best Practices

One project per application - Keep projects isolated
Commit config.yaml - Share configuration with team
Use components - Logical grouping over individual services
Document models - List required AI models in README
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

Getting Started

Core Concepts

Using Services

CLI Commands

Troubleshooting

Projects

Projects

Project Structure

Configuration File

Project Types

Project Lifecycle

1. Initialization

2. Setup

3. Development

4. Reset/Cleanup

Component System

Port Management

Default Ports

Port Allocation

Data Management

Data Persistence

Backup and Restore

Multiple Projects

Environment Variables

Project Templates

Version Control

Recommended .gitignore

Troubleshooting

Best Practices

Next Steps

Configuration

CLI Commands

Services

Quick Start

Getting Started

Core Concepts

Using Services

CLI Commands

Troubleshooting

​Projects

​Project Structure

​Configuration File

​Project Types

​Project Lifecycle

​1. Initialization

​2. Setup

​3. Development

​4. Reset/Cleanup

​Component System

​Port Management

​Default Ports

​Port Allocation

​Data Management

​Data Persistence

​Backup and Restore

​Multiple Projects

​Environment Variables

​Project Templates

​Version Control

​Recommended .gitignore

​Sharing Projects

​Troubleshooting

​Best Practices

​Next Steps

Configuration

CLI Commands

Services

Quick Start

Projects

Project Structure

Configuration File

Project Types

Project Lifecycle

1. Initialization

2. Setup

3. Development

4. Reset/Cleanup

Component System

Port Management

Default Ports

Port Allocation

Data Management

Data Persistence

Backup and Restore

Multiple Projects

Environment Variables

Project Templates

Version Control

Recommended .gitignore

Sharing Projects

Troubleshooting

Best Practices

Next Steps