CanbiZ 3998b80194 Add comprehensive documentation for all project sections

Introduced new and updated documentation files across the docs/ directory, including project structure guides, function library references, and standardized READMEs for ct, install, vm, tools, api, and misc. This update fully documents all nine function libraries, provides quick start and learning paths, and mirrors the project structure for easier navigation and contribution.

2025-12-01 11:40:38 +01:00

3.9 KiB

Raw Blame History

Installation Scripts Documentation (/install)

This directory contains comprehensive documentation for installation scripts in the /install directory.

Overview

Installation scripts (install/*.sh) run inside LXC containers and handle application-specific setup, configuration, and deployment.

Documentation Structure

Each installation script category has documentation following the project pattern.

Key Resources

UPDATED_APP-install.md - Complete guide for creating install scripts
CONTRIBUTION_GUIDE.md - Contribution workflow
misc/install.func/ - Installation workflow documentation
misc/tools.func/ - Package installation documentation

Installation Script Flow

install/appname-install.sh (container-side)
    │
    ├─ Sources: $FUNCTIONS_FILE_PATH
    │  ├─ core.func (messaging)
    │  ├─ error_handler.func (error handling)
    │  ├─ install.func (setup)
    │  └─ tools.func (packages & tools)
    │
    ├─ 10-Phase Installation:
    │  1. OS Setup
    │  2. Base Dependencies
    │  3. Tool Setup
    │  4. Application Download
    │  5. Configuration
    │  6. Database Setup
    │  7. Permissions
    │  8. Services
    │  9. Version Tracking
    │  10. Final Cleanup
    │
    └─ Result: Application ready

Available Installation Scripts

See /install directory for all installation scripts. Examples:

pihole-install.sh - Pi-hole installation
docker-install.sh - Docker installation
wallabag-install.sh - Wallabag setup
nextcloud-install.sh - Nextcloud deployment
debian-install.sh - Base Debian setup
And 30+ more...

Quick Start

To understand how to create an installation script:

Read: UPDATED_APP-install.md
Study: A similar existing script in /install
Copy template and customize
Test in container
Submit PR

10-Phase Installation Pattern

Every installation script follows this structure:

Phase 1: OS Setup

setting_up_container
network_check
update_os

Phase 2: Base Dependencies

pkg_update
pkg_install curl wget git

Phase 3: Tool Setup

setup_nodejs "20"
setup_php "8.3"
setup_mariadb "11"

Phase 4: Application Download

git clone https://github.com/user/app /opt/app
cd /opt/app

Phase 5: Configuration

# Create .env files, config files, etc.
cat > .env <<EOF
SETTING=value
EOF

Phase 6: Database Setup

# Create databases, users, etc.
mysql -e "CREATE DATABASE appdb"

Phase 7: Permissions

chown -R appuser:appgroup /opt/app
chmod -R 755 /opt/app

Phase 8: Services

systemctl enable app
systemctl start app

Phase 9: Version Tracking

echo "1.0.0" > /opt/app_version.txt

Phase 10: Final Cleanup

motd_ssh
customize
cleanup_lxc

Contributing an Installation Script

Create ct/myapp.sh (host script)
Create install/myapp-install.sh (container script)
Follow 10-phase pattern in UPDATED_APP-install.md
Test in actual container
Submit PR with both files

Common Tasks

Create new installation script → UPDATED_APP-install.md
Install Node.js/PHP/Database → misc/tools.func/
Setup Alpine container → misc/alpine-install.func/
Debug installation errors → EXIT_CODES.md
Use dev mode → DEV_MODE.md

Alpine vs Debian

Debian-based → Use tools.func, install.func, systemctl
Alpine-based → Use alpine-tools.func, alpine-install.func, rc-service

Last Updated: December 2025 Maintainers: community-scripts team

3.9 KiB Raw Blame History