{"id":49656853,"url":"https://github.com/fquinto/alpinelinux","last_synced_at":"2026-05-06T10:32:32.380Z","repository":{"id":321403410,"uuid":"1085658241","full_name":"fquinto/alpinelinux","owner":"fquinto","description":"Chroot with Alpine Linux","archived":false,"fork":false,"pushed_at":"2025-10-29T12:11:54.000Z","size":11,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-29T14:12:58.123Z","etag":null,"topics":["alpinelinux","archlinux","chroot","debian","rootfs"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fquinto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-29T10:41:15.000Z","updated_at":"2025-10-29T12:10:02.000Z","dependencies_parsed_at":"2025-10-29T14:23:08.007Z","dependency_job_id":null,"html_url":"https://github.com/fquinto/alpinelinux","commit_stats":null,"previous_names":["fquinto/alpinelinux"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fquinto/alpinelinux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fquinto%2Falpinelinux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fquinto%2Falpinelinux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fquinto%2Falpinelinux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fquinto%2Falpinelinux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fquinto","download_url":"https://codeload.github.com/fquinto/alpinelinux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fquinto%2Falpinelinux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32689126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpinelinux","archlinux","chroot","debian","rootfs"],"created_at":"2026-05-06T10:32:31.596Z","updated_at":"2026-05-06T10:32:32.374Z","avatar_url":"https://github.com/fquinto.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alpine Linux Chroot Installer\n\nThis script installs Alpine Linux into a chroot environment and optionally sets up qemu-user and binfmt for emulating different architectures (e.g., armhf).\n\n## System Compatibility\n\nThe script supports automatic dependency installation on:\n- **Debian-based systems**: Automatic installation using apt-get\n- **ArchLinux**: Automatic installation using pacman\n- **Other Linux systems**: Basic functionality (manual dependency installation required)\n\n## Overview\n\nThe script creates a complete Alpine Linux chroot environment with the following features:\n\n1. **Multi-architecture support**: Can emulate different CPU architectures using QEMU\n2. **Automatic dependency management**: Installs required packages based on your system\n3. **Helper scripts**: Creates convenient entry and cleanup scripts\n4. **Filesystem binding**: Mounts necessary system directories\n\n### Generated Scripts\n\nThe installer creates two helper scripts in the chroot directory:\n\n#### enter-chroot\nThis script provides easy access to the chroot environment and:\n1. Saves environment variables specified by `$CHROOT_KEEP_VARS` and current directory\n2. Performs chroot into the target directory\n3. Starts a clean environment using `env -i`\n4. Switches user and simulates full login using `su -l`\n5. Loads saved environment variables and changes to saved directory\n6. Executes specified command or starts a shell\n\n#### destroy\nThis script safely unmounts all filesystems and optionally removes the chroot directory.\n\n## Prerequisites\n\n**Important**: This script must be run as root.\n\n### Debian Systems\n```bash\napt update\n# Dependencies are installed automatically if needed\n```\n\n### ArchLinux\n```bash\npacman -Sy\n# Dependencies are installed automatically if needed\n```\n\n### Other Systems\nInstall manually:\n- `curl` or `wget` for downloads\n- `qemu-user-static` (for architecture emulation)\n- `binfmt-support` or equivalent (for architecture emulation)\n\n## Installation\n\n```bash\n# Download the script\ncurl -fsSL https://raw.githubusercontent.com/fquinto/alpinelinux/main/alpine-rootfs-setup.sh -o alpine-rootfs-setup.sh\nchmod +x alpine-rootfs-setup.sh\n```\n\n## Quick Start\n\n```bash\n# One-line installation and setup\ncurl -fsSL https://raw.githubusercontent.com/fquinto/alpinelinux/main/alpine-rootfs-setup.sh | sudo sh\n```\n\n## Usage\n\n### Configuration Testing (No Root Required)\n```bash\n# Test configuration without actually installing\n./alpine-rootfs-setup.sh -D -a x86_64 -p \"bash coreutils curl\"\n```\n\n### Basic Installation\n```bash\nsudo ./alpine-rootfs-setup.sh\n```\n\n### Custom Installation\n```bash\nsudo ./alpine-rootfs-setup.sh -d /opt/my-alpine -p build-base -p cmake\n```\n\n### Cross-Architecture Installation\n```bash\nsudo ./alpine-rootfs-setup.sh -a armhf -d /opt/alpine-arm\n```\n\n### Working with the Chroot\n\n#### Enter as root\n```bash\n/opt/alpine-rootfs/enter-chroot\n```\n\n#### Enter as specific user\n```bash\n/opt/alpine-rootfs/enter-chroot -u username\n```\n\n#### Execute commands directly\n```bash\n/opt/alpine-rootfs/enter-chroot -u $USER ./build-script.sh\n```\n\n### Cleanup\n\n#### Unmount filesystems only\n```bash\n/opt/alpine-rootfs/destroy\n```\n\n#### Complete removal\n```bash\n/opt/alpine-rootfs/destroy --remove\n```\n\n## Command Line Options\n\n| Option | Environment Variable | Description | Default |\n|--------|---------------------|-------------|---------|\n| `-a ARCH` | `ARCH` | CPU architecture for the chroot. If different from host, will be emulated using qemu-user. Options: x86_64, x86, aarch64, armhf, armv7, loongarch64, ppc64le, riscv64, s390x | Host architecture |\n| `-b ALPINE_BRANCH` | `ALPINE_BRANCH` | Alpine branch to install | `latest-stable` |\n| `-d CHROOT_DIR` | `CHROOT_DIR` | Absolute path to chroot installation directory | `/opt/alpine-rootfs` |\n| `-i BIND_DIR` | `BIND_DIR` | Host directory to mount inside chroot at same path | PWD if under /home, otherwise none |\n| `-k CHROOT_KEEP_VARS` | `CHROOT_KEEP_VARS` | Environment variable names to pass to chroot (supports regex) | `ARCH CI QEMU_EMULATOR TRAVIS_.*` |\n| `-m ALPINE_MIRROR` | `ALPINE_MIRROR` | Alpine mirror URI for package downloads | `https://dl-cdn.alpinelinux.org/alpine` |\n| `-p ALPINE_PACKAGES` | `ALPINE_PACKAGES` | Alpine packages to install in chroot | `build-base ca-certificates ssl_client` |\n| `-r EXTRA_REPOS` | `EXTRA_REPOS` | Additional Alpine repositories to add | None |\n| `-t TEMP_DIR` | `TEMP_DIR` | Temporary files directory | `mktemp -d` |\n| `-n` | `SKIP_VERSION_CHECK` | Skip automatic version update check | `no` |\n| `-D` | `DRY_RUN` | Validate configuration without installing (no root required) | `no` |\n| `-h` | - | Show help and exit | - |\n| `-v` | - | Show version and exit | - |\n\n### Additional Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `APK_TOOLS_URI` | Custom URL for apk.static download. If unset, latest version is fetched automatically |\n| `APK_TOOLS_SHA256` | SHA-256 checksum for custom APK_TOOLS_URI (optional) |\n| `VERIFY_CHECKSUMS` | Set to `yes` to enable checksum verification for downloads (default: `no`) |\n\n**Note**: Each option can also be provided via environment variable. Command line options take precedence over environment variables.\n\n## Supported Architectures\n\n- **x86_64**: Intel/AMD 64-bit\n- **x86**: Intel/AMD 32-bit  \n- **aarch64**: ARM 64-bit\n- **armhf**: ARM hard-float\n- **armv7**: ARM version 7\n- **loongarch64**: LoongArch 64-bit\n- **ppc64le**: PowerPC 64-bit little-endian\n- **riscv64**: RISC-V 64-bit\n- **s390x**: IBM System/390 64-bit\n\n## Important Notes\n\n### Security Considerations\n- The script must run as root for chroot creation and filesystem mounting\n- Default PWD binding behavior exists for legacy compatibility but can be security-sensitive\n- Always review the directories being bound into the chroot\n- **Download Integrity**: The script relies on HTTPS for download security. APKINDEX checksums are for package content verification (handled by APK tools), not file integrity. Set `VERIFY_CHECKSUMS=yes` only when providing external file checksums.\n\n### Architecture Emulation\n- Cross-architecture support requires QEMU user-mode emulation\n- QEMU binaries are automatically installed on supported systems\n- Some performance impact is expected when using emulation\n- The ash shell in Alpine may not load login profiles correctly under QEMU emulation, which is why `/etc/profile` is explicitly sourced\n\n### System-Specific Notes\n\n#### ArchLinux\n- Uses `qemu-arch-extra` or `qemu-user-static-bin` from AUR\n- binfmt_misc support is usually built into the kernel\n- Manual package installation may be required: `pacman -S qemu-arch-extra`\n\n#### Debian\n- Uses standard repository packages: `qemu-user-static` and `binfmt-support`\n- Automatic package cache updates\n\n## Troubleshooting\n\n### Error: \\\"binfmt_misc not available\\\"\nOn ArchLinux, ensure your kernel has binfmt_misc support:\n```bash\nzcat /proc/config.gz | grep CONFIG_BINFMT_MISC\n```\n\n### Error: \\\"qemu-user-static not found\\\"\nTry manual installation:\n\n**ArchLinux:**\n```bash\n# Option 1: AUR package\nyay -S qemu-user-static-bin\n\n# Option 2: Official package\npacman -S qemu-arch-extra\n```\n\n**Debian:**\n```bash\napt-get update \u0026\u0026 apt-get install qemu-user-static\n```\n\n### Permission Issues\nEnsure you're running as root:\n```bash\n# Check current user\nid\n\n# If not root, use su or sudo to become root\nsu -\n# or if you have sudo access\nsudo -i\n```\n\n### Mount Issues\nIf you encounter filesystem mount problems:\n```bash\n# Check existing mounts\nmount | grep alpine\n\n# Manual cleanup if needed\numount -R /opt/alpine-rootfs\n```\n\n## Examples\n\n### Development Environment\n```bash\n# Create Alpine chroot with development tools\n./alpine-rootfs-setup.sh -p \\\"build-base git cmake ninja\\\"\n\n# Enter and start working\n/opt/alpine-rootfs/enter-chroot -u $USER\n```\n\n### Cross-Compilation Setup\n```bash\n# ARM development environment\n./alpine-rootfs-setup.sh -a armhf -d /opt/alpine-arm -p \\\"build-base gcc-arm-none-eabi\\\"\n\n# Enter ARM environment\n/opt/alpine-arm/enter-chroot\n```\n\n### CI/CD Integration\n```bash\n# Minimal Alpine for testing\n./alpine-rootfs-setup.sh -p \\\"busybox curl\\\"\n\n# Run tests in clean environment\n/opt/alpine-rootfs/enter-chroot ./run-tests.sh\n```\n\n## Common Use Cases\n\n### Docker Alternative\nUse Alpine chroot as a lightweight container alternative:\n```bash\n./alpine-rootfs-setup.sh -p \"nginx php8\"\n/opt/alpine-rootfs/enter-chroot nginx\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Commit your changes (`git commit -am 'Add my feature'`)\n4. Push to the branch (`git push origin feature/my-feature`)\n5. Create a Pull Request\n\n## License\n\nSee [LICENSE](LICENSE) file for details.\n\n## Status\n\n[![License](https://img.shields.io/github/license/fquinto/alpinelinux)](LICENSE)\n[![Latest Release](https://img.shields.io/github/v/release/fquinto/alpinelinux)](https://github.com/fquinto/alpinelinux/releases)\n[![Issues](https://img.shields.io/github/issues/fquinto/alpinelinux)](https://github.com/fquinto/alpinelinux/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffquinto%2Falpinelinux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffquinto%2Falpinelinux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffquinto%2Falpinelinux/lists"}