{"id":32777730,"url":"https://github.com/kendawson-online/aserve","last_synced_at":"2026-01-16T18:30:14.947Z","repository":{"id":322347828,"uuid":"1089147205","full_name":"kendawson-online/aserve","owner":"kendawson-online","description":"aserve provides an easy way to \"point and serve\" a folder on Linux without having to copy files to /var/www/html, set up Apache vhosts, create symbolic links, or modify permissions.","archived":false,"fork":false,"pushed_at":"2026-01-15T22:14:49.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T01:36:59.185Z","etag":null,"topics":["apache","apache2","bash","bash-script","debian","debian-linux","helper","helper-tool","linux","linuxmint","lmde","shell-script"],"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/kendawson-online.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-11-04T00:22:20.000Z","updated_at":"2026-01-15T22:14:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kendawson-online/aserve","commit_stats":null,"previous_names":["kendawson-online/aserve"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kendawson-online/aserve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kendawson-online%2Faserve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kendawson-online%2Faserve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kendawson-online%2Faserve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kendawson-online%2Faserve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kendawson-online","download_url":"https://codeload.github.com/kendawson-online/aserve/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kendawson-online%2Faserve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28480854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: 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":["apache","apache2","bash","bash-script","debian","debian-linux","helper","helper-tool","linux","linuxmint","lmde","shell-script"],"created_at":"2025-11-04T14:01:08.255Z","updated_at":"2026-01-16T18:30:14.854Z","avatar_url":"https://github.com/kendawson-online.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aserve — \"Apache serve\"\n\n**Version 1.0.5**\n\naserve provides an easy way to \"point and serve\" a folder without having to copy files to /var/www/html, set up Apache vhosts, create symbolic links, or modify permissions. \n\nTechnically, aserve is a bash shell script that temporarily bind-mounts a local folder into Apache's document root (/var/www/html), adds minimal ACLs so Apache's www-data user can read/traverse the files, reloads Apache, and cleans everything up when you stop it. \n\naserve is not intended for long-term file serving. (You should set up vhosts instead!)\n\n### This repository contains:\n- `aserve.sh` — the script to run on your Debian Linux machine\n- README.md - this file\n- LICENSE - the MIT license\n\n### Prerequisites\n- Debian-based system (tested on LMDE 7 but should work on most Debian/Ubuntu derivatives).\n- Apache2 installed and configured to serve `/var/www/html`.\n- `acl` package recommended (for setfacl): `sudo apt install acl`\n- `mount` and `setfacl` require root. `aserve` must be run with `sudo` for normal operation.\n- Optional utilities: `realpath` (recommended). The script has fallbacks to Python for path resolution.\n\n## How it works:\n\nThe script creates `/var/www/html/\u003calias\u003e` and does a `mount --bind /path/to/site /var/www/html/\u003calias\u003e`. Minimal ACLs are added for `www-data` (rx on the site, x on parent directories up to the user's home). Apache is reloaded so the site is available at `http://localhost/\u003calias\u003e`.\n\n#### What the script does\n\n1. Resolve requested path to absolute path.\n2. Validate that the directory exists.\n3. Choose an alias (basename or provided name). If that alias already exists in `/var/www/html`, append a timestamp.\n4. Grant minimal ACLs to `www-data` so Apache can read and traverse.\n5. Create the destination mountpoint and perform `mount --bind`.\n6. Reload Apache and print the served URL.\n7. If `-o` flag is passed, open URL in default browser. \n8. Wait until the process receives INT/TERM; then unmount, revoke ACLs, reload Apache.\n\n\u003cbr\u003e\n\n# Installation (one-time)\n1. Download, and make script executable:\n   ```bash\n   chmod +x /path/to/aserve.sh\n   ```\n2. Optionally, install to PATH and set permissions so you can run from anywhere:\n   ```bash\n   sudo cp /path/to/aserve.sh /usr/local/bin/aserve\n   sudo chown root:root /usr/local/bin/aserve\n   sudo chmod 755 /usr/local/bin/aserve\n   ```\n3. Verify install (should display version):\n   ```bash\n   aserve -v\n   ```\n\u003cbr\u003e\n\n# Usage\n\nServe `/home/ken/Dev/kdo` (using auto-derived alias `kdo`):\n  ```bash\n  sudo aserve /home/ken/Dev/kdo\n  # Now available at http://localhost/kdo\n  ```\nServe with an explicit alias:\n  ```bash\n  sudo aserve /home/ken/Dev/kdo foobar\n  # Now available at http://localhost/foobar\n  ```\nServe and auto-open site in default browser:\n   ```bash\n   sudo aserve -o /home/ken/Dev/kdo\n   # Opens http://localhost/kdo in the default web browser\n   ```\n\nShow help:\n  ```bash\n  aserve -h\n  ```\nShow version number:\n  ```bash\n  aserve -v\n  ```  \nClean up any previous mounts (see below for more info)\n  ```bash\n  sudo aserve --clean\n  ```  \n\n#### Usage Notes:\n\n- If `aliasname` is omitted, the script uses the basename of the supplied path (e.g. `/home/ken/Dev/kdo` → `kdo`).\n\n- If the desired alias already exists in `/var/www/html`, the script appends a timestamp to avoid overwriting.\n\n- Press `Ctrl+C` in the terminal running `aserve` to unmount, remove the mountpoint, revoke the ACLs, and reload Apache.\n\n\u003cbr\u003e\n\n# Stopping / Cleanup\n\nPress `Ctrl+C` in the terminal where you started `aserve`. The script traps INT/TERM and will:\n  - unmount the bind mount,\n  - remove the `/var/www/html/\u003calias\u003e` mountpoint,\n  - revoke the ACL entries it added,\n  - reload Apache.\n\n### Cleaning previously-created mounts (--clean)\n\n- If `aserve` exited unexpectedly or the machine rebooted and a bind mount remains, use `--clean` to attempt a safe recovery.\n\n- The script writes a lightweight record file after a successful mount at `/run/aserve/\u003calias\u003e.record` containing the original source path. `--clean` prefers using that record to find and clean the site.\n- When cleaning an alias, `aserve` will also attempt to detect any running `aserve` process(es) that reference the same source path or `/var/www/html/\u003calias\u003e`. If found, the cleaner offers to terminate those process(es) (SIGTERM, then SIGKILL if needed) so the original terminal process doesn't remain running after the mount is removed.\n- If the record is missing, `--clean \u003calias\u003e` will fall back to resolving `/var/www/html/\u003calias\u003e` with `findmnt` to determine the bind source.\n- `sudo aserve --clean \u003calias\u003e` (or `--clean /path/to/source`) will:\n  - prompt for confirmation,\n  - revoke the recursive `www-data` ACL on the recorded source (`setfacl -R -x u:www-data $SRC`),\n  - unmount `/var/www/html/\u003calias\u003e` if mounted,\n  - remove the mountpoint directory, remove the `/run/aserve/\u003calias\u003e.record` file (if present), and\n  - reload Apache.\n- `sudo aserve --clean` with no argument lists records in `/run/aserve/*.record` and lets you pick one interactively.\n\n### Cleanup Examples:\n```bash\n# Clean a specific alias using its record (preferred)\nsudo aserve --clean kdo\n\n# Clean by source path\nsudo aserve --clean /home/ken/Dev/kdo\n\n# Interactively choose a record to clean\nsudo aserve --clean\n```\n\nYou can also clean old (unused) mounts manually:\n  ```bash\n  sudo umount /var/www/html/\u003calias\u003e || true\n  sudo rmdir /var/www/html/\u003calias\u003e || true\n  sudo setfacl -R -x u:www-data /path/to/site || true\n  # And reload apache\n  sudo systemctl reload apache2\n  ```\n\n\u003cbr\u003e\n\n# Error handling \u0026 troubleshooting\n\n- \"Operation cannot be completed without root level access. Please use sudo.\"\n  - You attempted to run the script without root. Rerun with `sudo`.\n- \"The directory /resolved/path does not exist.\"\n  - The supplied path is invalid or non-existent. Verify the path and try again.\n- 403 Forbidden when loading the site in the browser:\n  - Check Apache error log for details:\n    ```bash\n    sudo tail -n 80 /var/log/apache2/error.log\n    ```\n  - Ensure `www-data` has traverse permission on every parent directory (the script tries to add these via ACLs). If `setfacl` is not available, install `acl`.\n  - Verify the mount exists:\n    ```bash\n    mount | grep /var/www/html/\u003calias\u003e\n    ```\n- If the script fails to unmount during cleanup, use the clean option (`--clean`). See the \"Stopping / Cleanup\" section above for more information.\n\n## Security notes\n- The script grants `rx` to `www-data` on your site folder and `x` on parent directories up to your home. This allows the Apache user to traverse and read the files. The script attempts to revoke the ACLs on exit.\n- Because it uses bind mounts and modifies ACLs, the script requires `sudo`. Use responsibly; only run it on systems you trust.\n- If you want passwordless operation for convenience, consider a targeted polkit rule limited to this exact command — but be aware this elevates privileges and has security implications.\n\n## Notes / caveats\n- The script assumes Apache serves from `/var/www/html`. If your configuration differs, pick an appropriate destination or adjust the script.\n- The script attempts to be careful with ACLs, but ACL support (`setfacl`) must be present. Install the `acl` package if needed.\n- The script uses `systemctl reload apache2` to refresh Apache. If your system's service name is different, adjust the script.\n- The `-o` flag uses `xdg-open` and invokes user's desktop session so browser reuses the existing profile (avoids prompts to choose a profile). This is best-effort and designed to be transparent to the user; if the session can't be detected, the script falls back to simply printing the URL on screen.\n\n## License\n\n[MIT](LICENSE) \n\n\n## Disclaimer\n\nThis script is intended as a quick developer convenience to preview sites using a real Apache server without creating persistent vhosts and should only be used on development boxes. **This script is not intended for production use!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkendawson-online%2Faserve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkendawson-online%2Faserve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkendawson-online%2Faserve/lists"}