---
name: apaxy
description: Apaxy recipe for open-forge. Customisable theme for Apache mod_autoindex that enhances web directory listings with CSS, JS, custom icons, and error pages. Source: https://github.com/oupala/apaxy
---

# Apaxy

Customisable theme built to enhance the experience of browsing web directories. Uses the Apache `mod_autoindex` module and CSS/JS to override the default style of a directory listing. Upstream: <https://github.com/oupala/apaxy>. Docs: <https://oupala.github.io/apaxy/>.

Apaxy is not a standalone server — it's a theme layer applied on top of an existing Apache HTTP Server directory listing. It adds CSS styling, custom media type icons, JS interactivity, custom error pages, and welcome messages to Apache's built-in directory browser.

## Compatible install methods

| Method | Platform | Notes |
|---|---|---|
| Script install (`apaxy-configure.sh`) | Apache 2.4+ on Linux | Automated. Edits `apaxy.config` then runs the shell script. |
| Manual install | Apache 2.4+ on Linux/Windows | Copy files, edit `.htaccess`. |
| Docker | Docker | Community image available; not official. |

## Inputs to collect

| Phase | Prompt | Notes |
|---|---|---|
| setup | "Apache web root path?" | e.g. `/var/www/html` — the `apacheWebRootPath` in `apaxy.config` |
| setup | "Path of the directory to theme?" | e.g. `/var/www/html/share` — the `installWebPath` |
| style | "Custom theme / color scheme?" | Optional. Default is dark. Themes available in `themes/` dir. |

## Software-layer concerns

- **Requires:** Apache 2.4+ with `mod_autoindex` and `mod_headers` enabled
- **Apache config:** The target directory must have `AllowOverride Options Indexes FileInfo`
- **Files installed into target dir:**
  - `.htaccess` — enables autoindex, sets custom header/footer
  - `header.html` — top of every directory listing
  - `footer.html` — bottom of every directory listing
  - `style/` — CSS files
  - `error/` — custom 404/500 pages
  - `icons/` — media-type icons

### Script install

```bash
# 1. Clone the repo
git clone https://github.com/oupala/apaxy.git
cd apaxy

# 2. Edit apaxy.config
#    Set apacheWebRootPath and installWebPath

# 3. Run as the web server user
sudo -u www-data ./apaxy-configure.sh

# Or pass values on the command line (see -h for options)
sudo -u www-data ./apaxy-configure.sh -w /var/www/html -d /var/www/html/share
```

### Manual install

1. Download and unzip `https://github.com/oupala/apaxy/archive/main.zip`
2. Copy contents of `/apaxy/` into your target directory (e.g. `/var/www/html/share/`)
3. Rename `htaccess.txt` to `.htaccess`
4. Edit `.htaccess` and replace all `{FOLDERNAME}` placeholders with your path (e.g. `/share`)
5. Ensure Apache has `AllowOverride Options Indexes FileInfo` for the target dir
6. Reload Apache: `systemctl reload apache2`

### Required Apache config

```apache
<Directory /var/www/html/share>
    AllowOverride Options Indexes FileInfo
    Options +Indexes
</Directory>
```

## Upgrade procedure

1. Pull latest from GitHub: `git pull origin main`
2. Re-run `apaxy-configure.sh` to copy updated files to the target directory
3. Custom changes to `header.html`, `footer.html`, or `style/` must be re-applied after upgrade (back them up first)

## Gotchas

- **`{FOLDERNAME}` placeholders**: must match the URL path of the directory, not the filesystem path. e.g. if the directory is at `http://example.com/files/`, use `/files`.
- **`mod_autoindex` must be enabled**: `a2enmod autoindex` on Debian/Ubuntu.
- **`mod_headers` for CORS**: if sharing files cross-origin, enable `mod_headers` too.
- **Windows/IIS not supported**: Apaxy is Apache-only; it uses `.htaccess` directives.
- **Visual style only**: Apaxy cannot change the HTML table structure generated by `mod_autoindex`. Only CSS/JS styling is possible.
- **No active development since 2024**: project is stable/feature-complete but not actively updated.

## References

- [Upstream README](https://github.com/oupala/apaxy#readme)
- [Project page](https://oupala.github.io/apaxy/)
