# Custom HTML

[![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/custom-html/status.svg)](https://build.coopcloud.tech/coop-cloud/custom-html)

Custom HTML website, served using Nginx.

<!-- metadata -->
* **Category**: Development
* **Status**: 2, beta
* **Image**: [`nginx`](https://hub.docker.com/_/nginx), 4, upstream
* **Healthcheck**: No
* **Backups**: No
* **Email**: N/A
* **Tests**: 2
* **SSO**: No
<!-- endmetadata -->

## Basic usage

1. Set up Docker Swarm and [`abra`]
2. Deploy [`coop-cloud/traefik`]
3. `abra app new custom-html`
4. `abra app config YOURAPPDOMAIN` - be sure to change `$DOMAIN` to something that resolves to
   your Docker swarm box
5. `abra app deploy YOURAPPDOMAIN`
6. Copy your files to the container, using something like
```
abra app cp YOURAPPDOMAIN index.html app:/usr/share/nginx/html
```

## Downloading and auto-updating from a Git repository

To automatically pull website contents from a Git repository on a schedule:

1. `abra app config YOURAPPDOMAIN`
2. Add or uncomment these lines and configure your repository and update schedule:
```
COMPOSE_FILE="$COMPOSE_FILE:compose.git-pull.yml"
GIT_REPO_URL="https://git.coopcloud.tech/yourorg/yourrepo"
GIT_BRANCH=main
CRON_SCHEDULE="*/10 * * * *"  # Default: every 10 minutes
```
3. `abra app deploy YOURAPPDOMAIN`
4. As the git-pull service has `replicas: 0` in `compose.git-pull.yml` and doesn't run by itself. It requires either:
- Deploying an instance of the [`coop-cloud/swarm-cronjob`] recipe on your server, OR
- A manual cronjob on the server running: `docker service scale <app_domain_tld>_git=1`

## Allowing upload via SSH/SFTP
To allow management of your site's files using scp, rsync or other SSH-based tools:
1. If you don't already have one, generate an SSH keypair using `ssh-keygen`
1. `abra app config YOURAPPDOMAIN`
2. Uncomment these lines and add your public key:
```
#COMPOSE_FILE="$COMPOSE_FILE:compose.sftp.yml"
#PUBLIC_KEY="ssh-ed25519 AAAAC3NzaJ1lZDI1NTE5AAAAIXqf4nxUxuGmLOaxXXXXXXXXoM/GwhcrAgmtbgXToaYmCJ user@host" # Replace with a public key you generate
```
3. `abra app undeploy YOURAPPDOMAIN`
3. `abra app deploy YOURAPPDOMAIN`
4. Test the SSH connection: `ssh -p 2220 sftp@YOURAPPDOMAIN`
5. You can copy local files into the server's web root with a command like: `scp -r -P 2220 * sftp@YOURAPPDOMAIN:/content`

## Redirect options

### Full redirect (of all URLs under specific path)

To redirect the entire domain or a specific path to another URL:

1. `abra app config YOURAPPDOMAIN`
2. Add or uncomment these lines:
```
REDIRECT_FROM_PATH=/  # Path to redirect from (with trailing slash)
REDIRECT_TO_URL=https://example.com/website/  # Target URL (with trailing slash)
REDIRECT_TYPE=redirect  # Use "redirect" (for HTTP 302) or "permanent" (for 301)
```
3. `abra app deploy YOURAPPDOMAIN`

This will redirect all requests matching `REDIRECT_FROM_PATH` to `REDIRECT_TO_URL`, carrying over the path. For example, `/blog/post` would redirect to `https://example.com/website/blog/post`.

### Fallback redirect for paths not matching a file

To serve static files normally but redirect requests for all non-existent paths to a dynamic site:

1. `abra app config YOURAPPDOMAIN`
2. Add or uncomment these lines:
```
FALLBACK_REDIRECT_URL=https://dynamic-site.example.com
FALLBACK_REDIRECT_TYPE=302
```
3. `abra app deploy YOURAPPDOMAIN`

This is useful for serving a static site alongside a dynamic one (that is running on a different [sub]domain) on the same domain. Existing static files are served directly, while missing URLs are redirected to the dynamic site with the full path preserved.

### Single-page application (SPA) handler

Similarly, to serve all non-existent paths with a single HTML file (common for React, Vue, etc.):

1. `abra app config YOURAPPDOMAIN`
2. Add or uncomment this line:
```
SINGLE_PAGE_SITE_HANDLER=/index.html
```
3. `abra app deploy YOURAPPDOMAIN`

This will serve the contents `/index.html` (as a rewrite rather than a redirect) for any route that doesn't match an existing file, allowing client-side routing to work properly.

**Note:** `FALLBACK_REDIRECT_URL` and `SINGLE_PAGE_SITE_HANDLER` are mutually exclusive options.


[`abra`]: https://git.autonomic.zone/autonomic-cooperative/abra
[`coop-cloud/traefik`]: https://git.autonomic.zone/coop-cloud/traefik
[`coop-cloud/swarm-cronjob`]: https://git.coopcloud.tech/coop-cloud/swarm-cronjob