3998b80194
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.
298 lines
7.9 KiB
Markdown
298 lines
7.9 KiB
Markdown
# alpine-tools.func Documentation
|
|
|
|
## Overview
|
|
|
|
The `alpine-tools.func` file provides Alpine Linux-specific tool installation functions for package and service management within Alpine LXC containers. It complements `tools.func` with Alpine-specific implementations using the apk package manager.
|
|
|
|
## Purpose and Use Cases
|
|
|
|
- **Alpine Tool Installation**: Install services and tools using apk on Alpine
|
|
- **Package Management**: Safe apk operations with error handling
|
|
- **Service Setup**: Install and configure common services on Alpine
|
|
- **Dependency Management**: Handle Alpine-specific package dependencies
|
|
- **Repository Management**: Setup and manage Alpine package repositories
|
|
|
|
## Quick Reference
|
|
|
|
### Key Function Groups
|
|
- **Package Operations**: Alpine-specific apk commands with error handling
|
|
- **Service Installation**: Install databases, web servers, tools on Alpine
|
|
- **Repository Setup**: Configure Alpine community and testing repositories
|
|
- **Tool Setup**: Install development tools and utilities
|
|
|
|
### Dependencies
|
|
- **External**: `apk`, `curl`, `wget`
|
|
- **Internal**: Uses functions from `core.func`, `error_handler.func`
|
|
|
|
### Integration Points
|
|
- Used by: Alpine-based application install scripts
|
|
- Uses: Environment variables from build.func
|
|
- Provides: Alpine package and tool installation services
|
|
|
|
## Documentation Files
|
|
|
|
### 📊 [ALPINE_TOOLS_FUNC_FLOWCHART.md](./ALPINE_TOOLS_FUNC_FLOWCHART.md)
|
|
Visual execution flows for package operations and tool installation on Alpine.
|
|
|
|
### 📚 [ALPINE_TOOLS_FUNC_FUNCTIONS_REFERENCE.md](./ALPINE_TOOLS_FUNC_FUNCTIONS_REFERENCE.md)
|
|
Complete alphabetical reference of all Alpine tool functions.
|
|
|
|
### 💡 [ALPINE_TOOLS_FUNC_USAGE_EXAMPLES.md](./ALPINE_TOOLS_FUNC_USAGE_EXAMPLES.md)
|
|
Practical examples for common Alpine installation patterns.
|
|
|
|
### 🔗 [ALPINE_TOOLS_FUNC_INTEGRATION.md](./ALPINE_TOOLS_FUNC_INTEGRATION.md)
|
|
How alpine-tools.func integrates with Alpine installation workflows.
|
|
|
|
## Key Features
|
|
|
|
### Alpine Package Management
|
|
- **apk Add**: Safe package installation with error handling
|
|
- **apk Update**: Update package lists with retry logic
|
|
- **apk Del**: Remove packages and dependencies
|
|
- **Repository Configuration**: Add community and testing repos
|
|
|
|
### Alpine Tool Coverage
|
|
- **Web Servers**: nginx, lighttpd
|
|
- **Databases**: mariadb, postgresql, sqlite
|
|
- **Development**: gcc, make, git, node.js (via apk)
|
|
- **Services**: sshd, docker, podman
|
|
- **Utilities**: curl, wget, htop, vim
|
|
|
|
### Error Handling
|
|
- **Retry Logic**: Automatic recovery from transient failures
|
|
- **Dependency Resolution**: Handle missing dependencies
|
|
- **Lock Management**: Wait for apk locks to release
|
|
- **Error Reporting**: Clear error messages
|
|
|
|
## Function Categories
|
|
|
|
### 🔹 Package Management
|
|
- `apk_update()` - Update Alpine packages with retry
|
|
- `apk_add()` - Install packages safely
|
|
- `apk_del()` - Remove packages completely
|
|
|
|
### 🔹 Repository Functions
|
|
- `add_community_repo()` - Enable community repositories
|
|
- `add_testing_repo()` - Enable testing repositories
|
|
- `setup_apk_repo()` - Configure custom apk repositories
|
|
|
|
### 🔹 Service Installation Functions
|
|
- `setup_nginx()` - Install and configure nginx
|
|
- `setup_mariadb()` - Install MariaDB on Alpine
|
|
- `setup_postgresql()` - Install PostgreSQL
|
|
- `setup_docker()` - Install Docker on Alpine
|
|
- `setup_nodejs()` - Install Node.js from Alpine repos
|
|
|
|
### 🔹 Development Tools
|
|
- `setup_build_tools()` - Install gcc, make, build-essential
|
|
- `setup_git()` - Install git version control
|
|
- `setup_python()` - Install Python 3 and pip
|
|
|
|
## Alpine vs Debian Package Differences
|
|
|
|
| Package | Debian | Alpine |
|
|
|---------|:---:|:---:|
|
|
| nginx | `apt-get install nginx` | `apk add nginx` |
|
|
| mariadb | `apt-get install mariadb-server` | `apk add mariadb` |
|
|
| PostgreSQL | `apt-get install postgresql` | `apk add postgresql` |
|
|
| Node.js | `apt-get install nodejs npm` | `apk add nodejs npm` |
|
|
| Docker | Special setup | `apk add docker` |
|
|
| Python | `apt-get install python3 python3-pip` | `apk add python3 py3-pip` |
|
|
|
|
## Common Usage Patterns
|
|
|
|
### Basic Alpine Tool Installation
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
|
|
|
# Update package lists
|
|
apk_update
|
|
|
|
# Install nginx
|
|
apk_add nginx
|
|
|
|
# Start service
|
|
rc-service nginx start
|
|
rc-update add nginx
|
|
```
|
|
|
|
### With Community Repository
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
|
|
|
# Enable community repo for more packages
|
|
add_community_repo
|
|
|
|
# Update and install
|
|
apk_update
|
|
apk_add postgresql postgresql-client
|
|
|
|
# Start service
|
|
rc-service postgresql start
|
|
```
|
|
|
|
### Development Environment
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
|
|
|
# Install build tools
|
|
setup_build_tools
|
|
setup_git
|
|
setup_nodejs "20"
|
|
|
|
# Install application
|
|
git clone https://example.com/app
|
|
cd app
|
|
npm install
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### ✅ DO
|
|
- Always use `apk add --no-cache` to keep images small
|
|
- Call `apk_update()` before installing packages
|
|
- Use community repository for more packages (`add_community_repo`)
|
|
- Handle apk locks gracefully with retry logic
|
|
- Use `$STD` variable for output control
|
|
- Check if tool already installed before reinstalling
|
|
|
|
### ❌ DON'T
|
|
- Use `apt-get` commands (Alpine doesn't have apt)
|
|
- Install packages without `--no-cache` flag
|
|
- Hardcode Alpine-specific paths
|
|
- Mix Alpine and Debian commands
|
|
- Forget to enable services with `rc-update`
|
|
- Use `systemctl` (Alpine has OpenRC, not systemd)
|
|
|
|
## Alpine Repository Configuration
|
|
|
|
### Default Repositories
|
|
Alpine comes with main repository enabled by default. Additional repos:
|
|
|
|
```bash
|
|
# Community repository (apk add php, go, rust, etc.)
|
|
add_community_repo
|
|
|
|
# Testing repository (bleeding edge packages)
|
|
add_testing_repo
|
|
```
|
|
|
|
### Repository Locations
|
|
```bash
|
|
/etc/apk/repositories # Main repo list
|
|
/etc/apk/keys/ # GPG keys for repos
|
|
/var/cache/apk/ # Package cache
|
|
```
|
|
|
|
## Package Size Optimization
|
|
|
|
Alpine is designed for small container images:
|
|
|
|
```bash
|
|
# DON'T: Leaves package cache (increases image size)
|
|
apk add nginx
|
|
|
|
# DO: Remove cache to reduce size
|
|
apk add --no-cache nginx
|
|
|
|
# Expected sizes:
|
|
# Alpine base: ~5MB
|
|
# Alpine + nginx: ~10-15MB
|
|
# Debian base: ~75MB
|
|
# Debian + nginx: ~90-95MB
|
|
```
|
|
|
|
## Service Management on Alpine
|
|
|
|
### Using OpenRC
|
|
```bash
|
|
# Start service immediately
|
|
rc-service nginx start
|
|
|
|
# Stop service
|
|
rc-service nginx stop
|
|
|
|
# Restart service
|
|
rc-service nginx restart
|
|
|
|
# Enable at boot
|
|
rc-update add nginx
|
|
|
|
# Disable at boot
|
|
rc-update del nginx
|
|
|
|
# List enabled services
|
|
rc-update show
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "apk: lock is held by PID"
|
|
```bash
|
|
# Alpine apk database is locked (another process using apk)
|
|
# Wait a moment
|
|
sleep 5
|
|
apk_update
|
|
|
|
# Or manually:
|
|
rm /var/lib/apk/lock 2>/dev/null || true
|
|
apk update
|
|
```
|
|
|
|
### "Package not found"
|
|
```bash
|
|
# May be in community or testing repository
|
|
add_community_repo
|
|
apk_update
|
|
apk_add package-name
|
|
```
|
|
|
|
### "Repository not responding"
|
|
```bash
|
|
# Alpine repo may be slow or unreachable
|
|
# Try updating again with retry logic
|
|
apk_update # Built-in retry logic
|
|
|
|
# Or manually retry
|
|
sleep 10
|
|
apk update
|
|
```
|
|
|
|
### "Service fails to start"
|
|
```bash
|
|
# Check service status on Alpine
|
|
rc-service nginx status
|
|
|
|
# View logs
|
|
tail /var/log/nginx/error.log
|
|
|
|
# Verify configuration
|
|
nginx -t
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- **[alpine-install.func/](../alpine-install.func/)** - Alpine installation functions
|
|
- **[tools.func/](../tools.func/)** - Debian/standard tool installation
|
|
- **[core.func/](../core.func/)** - Utility functions
|
|
- **[error_handler.func/](../error_handler.func/)** - Error handling
|
|
- **[UPDATED_APP-install.md](../../UPDATED_APP-install.md)** - Application script guide
|
|
|
|
## Recent Updates
|
|
|
|
### Version 2.0 (Dec 2025)
|
|
- ✅ Enhanced apk error handling and retry logic
|
|
- ✅ Improved repository management
|
|
- ✅ Better service management with OpenRC
|
|
- ✅ Added Alpine-specific optimization guidance
|
|
- ✅ Enhanced package cache management
|
|
|
|
---
|
|
|
|
**Last Updated**: December 2025
|
|
**Maintainers**: community-scripts team
|
|
**License**: MIT
|