🚀 Local Projects

An automated, containerized local development environment powered by Ansible

Features • Quick Start • Documentation • Contributing

---

📖 Table of Contents

• Overview
• Features
• Available Applications
• Prerequisites
• Installation
• Configuration
• Deployment
• Uninstallation
• Application Access
• Project Structure
• Documentation
• GitHub Infrastructure as Code
• Development
• Troubleshooting
• Contributing
• Author
• License

📋 Overview

Local Projects is a fully automated infrastructure-as-code solution for deploying a complete local development environment. Using Ansible playbooks and Docker containers, it allows you to quickly spin up essential development tools and services on any system.

Perfect for developers who want:

• 🔄 Reproducible development environments
• 🐳 Containerized applications for isolation
• 🤖 AI/LLM capabilities with Ollama and Open WebUI
• 📊 Project management and collaboration tools
• 🔒 Secure configuration with Ansible Vault

✨ Features

• 🎯 One-Command Deployment - Deploy all applications with a single Ansible playbook
• 🔧 Modular Architecture - Enable/disable applications individually via simple configuration
• 🐳 Docker-Based - All applications run in isolated containers
• 🔐 Secure by Default - Sensitive data encrypted with Ansible Vault
• 🎨 Customizable - Easy configuration through YAML variables
• 🔄 Version Controlled - Infrastructure as Code approach
• 📦 Pre-configured - Ready-to-use setups with sensible defaults
• 🚀 GPU Support - NVIDIA GPU acceleration for Ollama (optional)
• ✅ Quality Assured - Pre-commit hooks for code quality (Ansible Lint, YAML Lint, ShellCheck, Terraform validators)

📱 Available Applications

The following applications can be deployed and managed through this project:

Application	Description	Status	Port	Official Site
🏠Homer	Beautiful dashboard to organize all your web services	✅ Available	8081	homer
🎨Excalidraw	Virtual collaborative whiteboard for sketching diagrams	✅ Enabled by default	8082	excalidraw.com
🗄️PostgreSQL	Powerful open-source relational database	⚠️ Available (commented out)	5432	postgresql.org
📊Planka	Elegant open-source project management (Trello alternative)	⚠️ Available (disabled)	8083	planka.app
🤖Ollama	Run large language models locally (Llama 3, Mistral, etc.)	✅ Enabled by default	11434	ollama.ai
🌐Open WebUI	Feature-rich web interface for Ollama and OpenAI APIs	✅ Enabled by default	8080	openwebui.com

Current Configuration

By default, the following applications are enabled in group_vars/all/main.yml:

deploy_homer: true
deploy_excalidraw: true
deploy_open_webui: true
deploy_ollama: true
deploy_planka: false  # Disabled by default

Note: PostgreSQL is available as a role but currently commented out in the main playbook.

⚡ Quick Start

Get up and running in under 5 minutes:

# 1. Clone the repository
git clone https://github.com/xgueret/local-projects.git
cd local-projects

# 2. Install dependencies
pip install -r requirements.txt
ansible-galaxy collection install -r requirements.yml

# 3. Configure vault password
mkdir -p ~/Workspace/.vault
echo "your-vault-password" > ~/Workspace/.vault/.vault_password

# 4. Deploy!
ansible-playbook deploy.yml

Access your applications:

• Open WebUI: http://localhost:8080
• Excalidraw: http://localhost:8082

For detailed setup instructions, see the Installation section below.

✅ Prerequisites

Ensure you have the following installed on your system:

Requirement	Version	Purpose	Installation
Python	3.x	Run Ansible	python.org
Ansible	2.14+	Automation engine	pip install ansible
Docker	Latest	Container runtime	docs.docker.com
Docker Compose	Latest	Multi-container orchestration	Included with Docker Desktop
Git	Latest	Version control	git-scm.com
NVIDIA Container Toolkit	Latest	GPU acceleration (optional)	NVIDIA Docs

System Requirements

• OS: Linux, macOS, or Windows (WSL2)
• RAM: 4GB minimum (8GB+ recommended for Ollama)
• Disk: 20GB free space minimum
• GPU (optional): NVIDIA GPU with CUDA support for Ollama acceleration

📥 Installation

1. Clone the repository:

git clone https://github.com/xgueret/local-projects.git
cd local-projects

2. Install Python dependencies:

pip install -r requirements.txt

3. Install Ansible collections:

ansible-galaxy collection install -r requirements.yml

4. Configure pre-commit hooks:

pre-commit install

⚙️ Configuration

Ansible Vault Setup

The project uses Ansible Vault to securely store sensitive information (passwords, API keys, etc.).

1. Create a vault password file:

# Create directory if it doesn't exist
mkdir -p ~/Workspace/.vault

# Create password file (use a strong password!)
echo "your-secure-vault-password" > ~/Workspace/.vault/.vault_password

# Secure the password file
chmod 600 ~/Workspace/.vault/.vault_password

2. The vault configuration is set in ansible.cfg:

vault_password_file = ~/Workspace/.vault/.vault_password

Configuration Files

You can customize the deployment by modifying these configuration files:

File	Purpose	Contains
group_vars/all/main.yml	Main configuration	App path, network settings, deployment flags
group_vars/all/postgres.yml	PostgreSQL settings	Database configuration
group_vars/all/vault/	Sensitive data (encrypted)	Passwords, API keys, secrets
roles/*/vars/main.yml	App-specific settings	Ports, versions, container names
ansible.cfg	Ansible behavior	Inventory, vault, connection settings

Enabling/Disabling Applications

Edit group_vars/all/main.yml to control which applications are deployed:

# Example: Enable all applications
deploy_homer: true
deploy_excalidraw: true
deploy_open_webui: true
deploy_ollama: true
deploy_planka: true  # Change to true to enable

Customizing Application Settings

Each application has its own configuration in roles/<app_name>/vars/main.yml. For example:

Ollama (roles/ollama/vars/main.yml):

ollama_use_gpu: true  # Enable/disable GPU acceleration
ollama_port: "11434"  # Change port if needed

Open WebUI (roles/open_webui/vars/main.yml):

open_webui_version: "v0.6.34"  # Specify version
open_webui_port: 8080          # Web interface port
open_webui_ollama_base_url: "http://127.0.0.1:11434"  # Ollama connection

🚀 Deployment

Deploy All Applications

Deploy all enabled applications with a single command:

ansible-playbook deploy.yml

This will:

1. Create the application directory structure
2. Set up a Docker network (local_network)
3. Deploy all applications where deploy_<app>: true in configuration
4. Start all containers

Deploy Specific Applications

Use tags to deploy only specific applications:

# Deploy only Ollama and Open WebUI
ansible-playbook deploy.yml --tags "ollama,open_webui"

# Deploy only Excalidraw
ansible-playbook deploy.yml --tags "excalidraw"

Available Deployment Tags

Tag	Application	Status
excalidraw	Excalidraw whiteboard	✅ Active in playbook
ollama	Ollama LLM engine	✅ Active in playbook
open_webui	Open WebUI interface	✅ Active in playbook
homer	Homer dashboard	⚠️ Commented out in playbook
postgres	PostgreSQL database	⚠️ Commented out in playbook
planka	Planka project management	⚠️ Commented out in playbook

Verify Deployment

After deployment, check that containers are running:

docker ps

You should see containers named:

• ollama
• open-webui
• excalidraw
• (plus any other enabled applications)

🗑️ Uninstallation

⚠️ Important Warning

Running uninstall.yml without tags will remove ALL applications! Always use tags unless you want to completely reset your environment.

Uninstall Specific Applications (Recommended)

# Uninstall a single application
ansible-playbook uninstall.yml --tags "ollama"

# Uninstall multiple applications
ansible-playbook uninstall.yml --tags "excalidraw,ollama,open_webui"

Uninstall All Applications

# This will remove EVERYTHING!
ansible-playbook uninstall.yml

What Gets Removed

The uninstall playbook performs the following actions:

• ✅ Stops and removes Docker containers
• ✅ Removes Ollama CLI tools (if uninstalling Ollama)
• ❌ Preserves data volumes (must be manually removed if desired)
• ❌ Preserves configuration files

Available Uninstall Tags

All applications support uninstallation via tags:

Tag	Application
postgres	PostgreSQL database
homer	Homer dashboard
excalidraw	Excalidraw whiteboard
planka	Planka project management
ollama	Ollama LLM engine
open_webui	Open WebUI interface

Manual Cleanup (Optional)

To completely remove data and free up disk space:

# Remove application directory (⚠️ deletes all data!)
rm -rf ~/Workspace/07-local/app

# Remove Docker volumes
docker volume prune

# Remove Docker network
docker network rm local_network

🔗 Application Access

Once deployed, access your applications through these URLs:

Application	URL	Description
🌐Open WebUI	http://localhost:8080	Web interface for Ollama models
🎨Excalidraw	http://localhost:8082	Collaborative whiteboard
🏠Homer	http://localhost:8081	Dashboard (if enabled)
📊Planka	http://localhost:8083	Project management (if enabled)
🤖Ollama API	http://localhost:11434	Direct API access for Ollama
🗄️PostgreSQL	localhost:5432	Database (internal only)

First-Time Setup

For Open WebUI:

1. Navigate to http://localhost:8080
2. Create your admin account on first visit
3. Download models from the Settings > Models section
4. Start chatting!

For Ollama CLI:

# The Ollama CLI is automatically installed and available
ollama-local pull llama3  # Download a model
ollama-local run llama3   # Run the model

📁 Project Structure

local-projects/
│
├── 📋 Ansible Configuration
│   ├── ansible.cfg                 # Ansible configuration
│   ├── deploy.yml                  # Main deployment playbook
│   ├── uninstall.yml               # Application removal playbook
│   └── inventory.yml               # Ansible inventory (localhost)
│
├── ⚙️ Configuration & Variables
│   └── group_vars/all/
│       ├── main.yml                # Main config (deployment flags, paths)
│       ├── postgres.yml            # PostgreSQL configuration
│       └── vault/                  # 🔒 Encrypted sensitive data (Ansible Vault)
│
├── 🎭 Application Roles
│   └── roles/
│       ├── common/                 # Shared tasks and configurations
│       ├── excalidraw/             # Excalidraw whiteboard
│       ├── homer/                  # Homer dashboard
│       ├── ollama/                 # Ollama LLM engine
│       ├── open_webui/             # Open WebUI interface
│       ├── planka/                 # Planka project management
│       └── postgres/               # PostgreSQL database
│       │
│       └── Each role contains:
│           ├── tasks/
│           │   ├── main.yml        # Deployment tasks
│           │   └── uninstall.yml   # Cleanup tasks
│           ├── vars/main.yml       # Role-specific variables
│           └── templates/          # Configuration templates
│
├── 📚 Documentation
│   └── docs/
│       ├── OPEN_WEBUI_CONFIGURATION.md   # Open WebUI setup guide
│       ├── QUICK_START_OLLAMA.md         # Quick start for AI features
│       └── examples/                     # Configuration examples
│
├── 🛠️ Utilities & Scripts
│   ├── scripts/
│   │   └── test-ollama-connection.sh    # Test Ollama API
│   ├── requirements.txt                  # Python dependencies
│   └── requirements.yml                  # Ansible collections
│
├── ☁️ Infrastructure as Code
│   └── github/                    # Terraform for GitHub repo management
│       ├── main.tf
│       ├── providers.tf
│       ├── variables.tf
│       └── ...
│
├── 🔧 Development Tools
│   ├── .pre-commit-config.yaml    # Pre-commit hooks configuration
│   ├── .vscode/                   # VSCode workspace settings
│   └── .gitignore
│
└── 📄 Project Files
    ├── README.md                  # This file
    └── LICENSE                    # MIT License

Key Directories Explained

Directory	Purpose
roles/	Contains Ansible roles for each application (modular architecture)
group_vars/all/	Global configuration variables and deployment settings
group_vars/all/vault/	Encrypted secrets (passwords, API keys) using Ansible Vault
docs/	Detailed documentation and configuration guides
scripts/	Helper scripts for testing and maintenance
github/	Terraform configurations for managing GitHub infrastructure

📚 Documentation

• Quick Start: Ollama + Open WebUI - Get started quickly with Ollama and Open WebUI
• Open WebUI Configuration - Detailed configuration options for Open WebUI
• Configuration Examples - Example configuration files

🤖 Ollama Configuration

The Ollama integration includes:

• Automatic GPU support detection and configuration
• Automatic CLI extraction from container for local usage
• Profile script for easy CLI access via ollama-local command
• Health checks to ensure the API is ready

For GPU acceleration, ensure the NVIDIA Container Toolkit is installed and the ollama_use_gpu variable is set to true in your configuration.

Open WebUI Connection to Ollama

Open WebUI needs to communicate with Ollama. The connection URL can be configured in two ways:

Option 1: Via container name (recommended)

# In group_vars/all/main.yml
open_webui_ollama_base_url: "http://ollama:11434"

Option 2: Via host (current default)

# In roles/open_webui/vars/main.yml
open_webui_ollama_base_url: "http://127.0.0.1:11434/"

For detailed configuration options and troubleshooting, see Open WebUI Configuration Guide.

☁️ GitHub Infrastructure as Code

The project includes Terraform configurations to manage GitHub repositories in the github/ directory:

1. Change to the GitHub directory:

cd github

2. Initialize Terraform:

terraform init

3. Deploy the infrastructure:

terraform apply

👨‍💻 Development

This project follows best practices for Infrastructure as Code with comprehensive quality checks.

Pre-commit Hooks

The project uses pre-commit to ensure code quality. Install hooks after cloning:

pre-commit install

Code Quality Tools

All of these run automatically on commit:

Tool	Purpose	Files Checked
🔍 Ansible Lint	Enforces Ansible best practices	*.yml playbooks and roles
📝 YAML Lint	Validates YAML syntax and formatting	*.yml, *.yaml
🛡️ ShellCheck	Identifies issues in shell scripts	*.sh
🔧 Terraform fmt	Formats Terraform files	*.tf
🔧 Terraform validate	Validates Terraform syntax	*.tf
🔧 TFLint	Lints Terraform configurations	*.tf
🐍 Flake8	Python code linter	*.py
🔐 Vault Check	Ensures sensitive files are encrypted	vault/*
✂️ Trailing Whitespace	Removes trailing whitespace	All files
📄 EOF Fixer	Ensures files end with newline	All files

Manual Testing

# Run pre-commit checks manually
pre-commit run --all-files

# Test Ollama connection
bash scripts/test-ollama-connection.sh

# Validate Ansible syntax
ansible-playbook deploy.yml --syntax-check

# Check what would change (dry run)
ansible-playbook deploy.yml --check --diff

Adding a New Application

1. Create a new role in roles/<app_name>/
2. Define variables in roles/<app_name>/vars/main.yml
3. Create deployment tasks in roles/<app_name>/tasks/main.yml
4. Create uninstall tasks in roles/<app_name>/tasks/uninstall.yml
5. Add role to deploy.yml with appropriate conditions and tags
6. Add uninstall task to uninstall.yml
7. Update documentation

Example role structure:

roles/myapp/
├── tasks/
│   ├── main.yml        # Deployment logic
│   └── uninstall.yml   # Cleanup logic
├── vars/
│   └── main.yml        # App-specific variables
└── templates/
    └── config.yml.j2   # Configuration templates (if needed)

🚨 Troubleshooting

Common Issues

Docker Permission Denied

Problem: permission denied while trying to connect to the Docker daemon socket

Solution:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect
# Or use: newgrp docker

# Verify
docker ps

Ansible Vault Password Error

Problem: ERROR! Attempting to decrypt but no vault secrets found

Solution:

# Ensure the vault password file exists
ls -la ~/Workspace/.vault/.vault_password

# Create if missing
mkdir -p ~/Workspace/.vault
echo "your-vault-password" > ~/Workspace/.vault/.vault_password
chmod 600 ~/Workspace/.vault/.vault_password

# Verify path in ansible.cfg
grep vault_password_file ansible.cfg

Ollama GPU Not Working

Problem: Ollama not using GPU acceleration

Solution:

# 1. Install NVIDIA Container Toolkit
# Follow: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

# 2. Verify installation
docker info | grep -i nvidia

# 3. Enable GPU in configuration
# Edit roles/ollama/vars/main.yml
ollama_use_gpu: true

# 4. Redeploy
ansible-playbook deploy.yml --tags "ollama"

Port Already in Use

Problem: Error: bind: address already in use

Solution:

# Find what's using the port (example for port 8080)
sudo lsof -i :8080
# or
sudo netstat -tulpn | grep :8080

# Option 1: Stop the conflicting service
# Option 2: Change port in roles/<app>/vars/main.yml
# Example: open_webui_port: 8081

# Redeploy
ansible-playbook deploy.yml --tags "open_webui"

Open WebUI Can't Connect to Ollama

Problem: Open WebUI shows "Cannot connect to Ollama"

Solution:

# 1. Verify Ollama is running
docker ps | grep ollama

# 2. Test Ollama API
curl http://localhost:11434/api/version

# 3. Check Open WebUI configuration
# Edit roles/open_webui/vars/main.yml
open_webui_ollama_base_url: "http://ollama:11434"  # Use container name
# or
open_webui_ollama_base_url: "http://127.0.0.1:11434"  # Use host

# 4. Redeploy Open WebUI
ansible-playbook deploy.yml --tags "open_webui"

Pre-commit Hooks Failing

Problem: Pre-commit hooks prevent commits

Solution:

# Run pre-commit manually to see errors
pre-commit run --all-files

# Update hooks to latest version
pre-commit autoupdate

# If you need to skip hooks temporarily (not recommended)
git commit --no-verify -m "message"

Getting Help

If you encounter issues not covered here:

1. Check the logs:

   # Ansible output
   ansible-playbook deploy.yml -vvv
   
   # Docker container logs
   docker logs <container_name>

2. Search existing issues: GitHub Issues

3. Create a new issue: Provide details about your environment, error messages, and steps to reproduce

🤝 Contributing

Contributions are welcome and appreciated! This project benefits from community involvement.

How to Contribute

1. Fork the repository

   # Click "Fork" on GitHub, then:
   git clone https://github.com/YOUR-USERNAME/local-projects.git
   cd local-projects

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Add a new application role
   • Improve documentation
   • Fix bugs
   • Enhance existing features

4. Test your changes

   # Run pre-commit checks
   pre-commit run --all-files
   
   # Test deployment
   ansible-playbook deploy.yml --check

5. Commit your changes

   git add .
   git commit -m "feat: add amazing feature"

   Follow Conventional Commits format:

   • feat: - New features
   • fix: - Bug fixes
   • docs: - Documentation changes
   • refactor: - Code refactoring
   • test: - Adding tests
   • chore: - Maintenance tasks

6. Push and create Pull Request

   git push origin feature/amazing-feature

   Then create a Pull Request on GitHub

Contribution Ideas

• 📦 Add new application roles (Portainer, Grafana, etc.)
• 📚 Improve documentation
• 🐛 Fix bugs or improve error handling
• ✨ Enhance existing features
• 🧪 Add tests
• 🎨 Improve UI/UX of configurations

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Focus on what is best for the community

👥 Author

Xavier GUERET

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

What this means:

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Private use
• ⚠️ No liability
• ⚠️ No warranty

---

⭐ If this project helped you, please consider giving it a star! ⭐