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:The
.localcloud
directory contains all LocalCloud-specific files. Your application code lives alongside it.Configuration File
The heart of a LocalCloud project is theconfig.yaml
file:
Project Types
LocalCloud supports different project types with optimized defaults:- Custom
- Chat
- RAG
- API
Default type - You choose exactly what services to includeBest for: Specific requirements, minimal setups
Project Lifecycle
1. Initialization
2. Setup
- Select project type
- Choose components
- Pick AI models
- Configure services
3. Development
4. Reset/Cleanup
Component System
Components are logical groupings of functionality:LLM Component
LLM Component
Language model for text generation
- Service: Ollama
- Models: Llama, Mistral, etc.
- Use: Chat, completion, reasoning
Embedding Component
Embedding Component
Convert text to vectors
- Service: Ollama
- Models: nomic-embed-text, mxbai-embed-large
- Use: Semantic search, RAG
Database Component
Database Component
Persistent data storage
- Service: PostgreSQL
- Extensions: pgvector for embeddings
- Use: Application data, vector storage
Cache Component
Cache Component
High-speed data access
- Service: Redis
- Features: Caching, pub/sub
- Use: Session storage, queues
Storage Component
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:Backup and Restore
Multiple Projects
You can have multiple LocalCloud projects: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:Project Templates
Create projects from templates:- Pre-configured services
- Example code
- Best practices
- Documentation
Version Control
Recommended .gitignore
Sharing Projects
To share a LocalCloud project:- Commit
.localcloud/config.yaml
- Document required models in README
- Other developers run:
Troubleshooting
Project already initialized
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
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
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