lxd/
├── run.sh                         # Main management script ⭐
├── .lxd-compose.yml               # Main lxd-compose config
├── envs/
│   └── infinibay.yml              # Infinibay project definition
├── profiles/
│   └── templates/                 # LXD profile templates
├── values.yml.example             # Configuration template
├── setup.sh                       # Automated installation
├── INSTALL.md                     # Complete guide
└── README.md                      # This file

• setup.sh – Installs LXD, lxd-compose, detects your distro and package manager, auto-detects LXD path, generates .env with secure passwords
• newgrp lxd – ⚠️ REQUIRED – Activates lxd group permissions
• .env configuration – ⚠️ IMPORTANT – Review and change ADMIN_PASSWORD (auto-generated passwords should be personalized!)
• ./run.sh – Intelligent orchestration: creates containers, provisions software, starts everything
  • Checks if environment exists → creates if not
  • Checks if containers are running → starts if stopped
  • Checks if provisioned → provisions if not (tracked via LXD metadata)
  • Skips already-completed steps automatically
• Containers have shared /opt/infinibay directory (your code)
• Data persists in /data directories even if containers are destroyed

Important: Group Membership

After running setup.sh, you may need to activate the lxd group:

Option 1 (Quick – current session only):

Option 2 (Permanent – requires re-login):

logout
# Then login again

How to check if you’re in the group:

groups | grep lxd
# Should show 'lxd' in the output

Common Operations

Recommended Workflow (Smart Default)

# One command does everything - creates, provisions, and starts
./run.sh              # Smart default - handles everything automatically

# Fresh start - destroy and recreate everything
./run.sh redo         # or: ./run.sh rd

# Quick status check
./run.sh status       # or: ./run.sh s

Using run.sh (All Commands)

# Smart default workflow (recommended)
./run.sh              # Does everything: create → provision → start

# Manual step-by-step (if you prefer explicit control)
./run.sh apply        # Shortcuts: a, ap - Create containers
./run.sh provision    # Shortcuts: p, pr - Install software

# Container management
./run.sh status       # Shortcuts: s, st - Check status
./run.sh destroy      # Shortcuts: d, de - Remove containers
./run.sh redo         # Shortcut: rd - Destroy and recreate (fresh start)
./run.sh restart      # Shortcuts: r, re - Legacy alias for redo

# Execute commands in containers
./run.sh exec backend bash      # Shortcuts: e, ex
./run.sh exec postgres psql -U infinibay
./run.sh exec frontend npm run dev

# Follow container logs
./run.sh logs backend           # Shortcuts: l, lo
./run.sh logs postgres

# Update profiles only (after modifying templates)
./run.sh setup-profiles         # Shortcut: sp

# Show help with all shortcuts
./run.sh help

Complete shortcut reference:

Direct LXC Commands

# View container status
sg lxd -c "lxc list"

# Execute commands
sg lxd -c "lxc exec infinibay-backend -- bash"

# Create snapshot
sg lxd -c "lxc snapshot infinibay-backend backup-$(date +%Y%m%d)"

# List snapshots
lxc info infinibay-backend

Current Status

Implemented and Working:

• ✅ Creates 4 Ubuntu containers with resource limits
• ✅ Mounts shared /opt/infinibay directory (your code)
• ✅ Persistent /data directories for each service
• ✅ Automated provisioning scripts for all containers
• ✅ PostgreSQL installation and configuration
• ✅ Redis installation and configuration
• ✅ Node.js 20.x LTS + npm
• ✅ Rust toolchain (for libvirt-node native modules)
• ✅ libvirt + KVM with /dev/kvm device access
• ✅ Systemd services ready for backend/frontend
• ✅ Network connectivity between containers
• ✅ Universal package manager support (apt/dnf/zypper/pacman)
• ✅ Automatic LXD path detection (snap vs native)
• ✅ Smart default orchestration with state tracking
• ✅ Provisioning state persistence via LXD metadata

Still Manual:

• ⏳ npm install in backend/frontend
• ⏳ Database migrations
• ⏳ Starting Infinibay services
• ⏳ Application configuration

After provisioning, you need to:

1. Install npm dependencies in backend/frontend
2. Run database migrations
3. Configure and start Infinibay services

See INSTALL.md for detailed instructions.

Troubleshooting

“No project selected” error

# Make sure you specify the project name
lxd-compose apply infinibay  # ✓ Correct
lxd-compose apply             # ✗ Wrong

“Unable to read the configuration file” error

# You need to be in the lxd group
newgrp lxd
# Or logout/login

“Permission denied” on LXD socket

# Check if you're in lxd group
groups | grep lxd

# If not, the setup script should have added you
# Just run:
newgrp lxd

Smart default fails at provisioning step

# Check individual container status
./run.sh status

# Use redo to start fresh (destroys and recreates everything)
./run.sh redo

Want to force re-provisioning

# Option 1: Use redo command (destroys and recreates everything)
./run.sh redo

# Option 2: Manually clear provisioning state for specific container
lxc config unset infinibay-backend user.provisioned
lxc config unset infinibay-frontend user.provisioned
lxc config unset infinibay-postgres user.provisioned
lxc config unset infinibay-redis user.provisioned
# Then run: ./run.sh

vs Native Installer

Recommendation: Use the native installer for production deployments until LXD provisioning is complete.

Contributing

See INSTALL.md for development workflows.

References

• LXD Documentation
• lxd-compose Documentation
• Infinibay Installer – Recommended for production

Last Updated: 2025-11-21
Status: Production Ready