generated from coop-cloud/example
112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# Custom HTML
|
|
|
|
[](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
|