<p align="center"> <h1 align="center">Erin</h1> <p align="center"> Self-hostable TikTok feed for your clips <br /> Make a TikTok feed with your own videos </p> </p>

| | | | |:-------------------------:|:-------------------------:|:-------------------------:| |<img width="1604" src="/screenshots/SCREENSHOT-1.png"/> | <img width="1604" src="/screenshots/SCREENSHOT-2.png"/> | <img width="1604" src="/screenshots/SCREENSHOT-3.png"/> |

Introduction

Erin is a simple and self-hostable service that enables you to view your own clips using TikTok's well-known vertical swipe feed. A request was made on Reddit for a self-hostable app that can show filtered videos using TikTok's interface, so I made it.

Features

Erin has all these features implemented :

Display your own videos using TikTok's swipe feed
Mask the videos you don't want to see in your feed*
Choose which feed (playlist) you want to play**
Autoplay your feed without even swiping
Seek forward and backward using your keyboard, or using double taps
Enter / Exit fullscreen using a double tap in the center
Share any clip with a direct link
Show video and playlist metadata using TikTok's UI***
Simple lazy-loading mechanism for your videos
Automatic clip naming based on file name
Simple and optional security using a master password
Support for Horizontal and Vertical scroll direction
Support for starting video playback from the start, middle, or random point in the video
Support for custom styling****
Support for HTTP and HTTPS
Support for Docker / proxy deployment

On top of these, please note that Erin is only a React app powered entirely by Caddy. Caddy takes care of authentication, serving static files, and serving the React app all at once.

*: You can mask videos to hide them from your feed. Should you want to see which videos were masked, and even unmask them, you can long-press the Mask button, and the manager will open.

**: By default, Erin will create a random feed from all the videos in your folder and its subdirectories. However, if you would like to create custom feeds (playlists), you can create subdirectories and organize your videos accordingly. For example: https://my-server.tld/directory-a will create a feed from the videos located in the /directory-a directory, and it works with any path (so, nested folders are supported).

***: You can show a channel (with an avatar and name), a caption and a link for all your videos using a metadata file. The metadata file can be located anywhere inside your videos folder, and it must match its associated video's filename, while replacing the extension with JSON. For example: my-video.mp4 can have its metadata in my-video.json. The metadata format is shown here, and note that you can use raw HTML in the caption for custom styling and effects. Moreover, you may define folder-level metadata to set a name and avatar for any playlist, and those information will be used for all the videos within that folder if they don't have their own metadata already. The folder-level metadata format is shown here and it belongs to a file named metadata.json inside your folder.

****: You can inject your own stylesheet to customize the appearance of the app by doing two things: 1) set USE_CUSTOM_SKIN to true, and 2) mount a custom.css file onto /srv/custom.css in your container.

For more information, read about Configuration.

Deployment and Examples

Before proceeding, regardless of Docker, Docker Compose, or a standalone deployment, please make sure that you have created a videos directory containing all your video files. Later on, this directory will be made available to your instance of Erin (by binding a volume to your Docker container, or putting the directory next to your Caddyfile).

Deploy with Docker

You can run Erin with Docker on the command line very quickly.

You can use the following commands :

# Create a .env file
touch .env

# Edit .env file ...

# Option 1 : Run Erin attached to the terminal (useful for debugging)
docker run --env-file .env -p <YOUR-PORT-MAPPING> -v ./videos:/srv/videos:ro mosswill/erin

# Option 2 : Run Erin as a daemon
docker run -d --env-file .env -p <YOUR-PORT-MAPPING> -v ./videos:/srv/videos:ro mosswill/erin

Note : A sample.env file is located at the root of the repository to help you get started

Note : When using docker run --env-file, make sure to remove the quotes around AUTH_ENABLED and AUTH_SECRET, or else your container might crash due to unexpected interpolation and type conversions operated by Docker behind the scenes.

Deploy with Docker Compose

To help you get started quickly, a few example docker-compose files are located in the "examples/" directory.

Here's a description of every example :

docker-compose.simple.yml: Run Erin as a front-facing service on port 443, with environment variables supplied in the docker-compose file directly.
docker-compose.proxy.yml: A setup with Erin running on port 80, behind a proxy listening on port 443.

When your docker-compose file is on point, you can use the following commands :

# Run Erin in the current terminal (useful for debugging)
docker-compose up

# Run Erin in a detached terminal (most common)
docker-compose up -d

# Show the logs written by Erin (useful for debugging)
docker logs <NAME-OF-YOUR-CONTAINER>

Configuration

To run Erin, you will need to set the following environment variables in a .env file :

Note : Regular environment variables provided on the commandline work too

Note : A sample.env file is located at the root of the repository to help you get started

| Parameter | Type | Description | Default | | :---------------------- | :-------- | :------------------------- | ------- | | PUBLIC_URL | boolean | The public URL used to remotely access your instance of Erin. (Please include HTTP / HTTPS and the port if not standard 80 or 443. Do not include a trailing slash) (Read the official Caddy documentation) | https://localhost
| AUTH_ENABLED | string | Whether Basic Authentication should be enabled. (This parameter is case sensitive) (Possible values : true, false) | true | | AUTH_SECRET | string | The secure hash of the password used to protect your instance of Erin. | Hash of secure-password | | APP_TITLE | string | The custom title that you would like to display in the browser's tab. (Tip: You can use [VIDEO_TITLE] here if you want Erin to dynamically display the title of the current video.) | Erin - TikTok feed for your own clips | | AUTOPLAY_ENABLED | boolean | Whether autoplay should be enabled. (This parameter is case sensitive) (Possible values : true, false) | false | | PROGRESS_BAR_POSITION | string | Where the progress bar should be located on the screen. (This parameter is case sensitive) (Possible values : bottom, top) | bottom | | IGNORE_HIDDEN_PATHS | boolean | Whether all hidden files and directories (starting with a dot) should be ignored by Erin, and not loaded or scanned altogether | false | | SCROLL_DIRECTION | string | The scroll direction of your video feed. (Possible values : vertical, horizontal ) | vertical | | USE_CUSTOM_SKIN | boolean | Whether a custom skin should be loaded on startup. (Possible values : true, false) | false | | VIDEO_START_POSITION | string | Where videos start playing. (Possible values : start, middle, random) | start |

Tip : To generate a secure hash for your instance, use the following command :

docker run caddy caddy hash-password --plaintext "your-new-password"

Note : When using docker-compose.yml environment variables, if your password hash contains dollar signs: double them all, or else the app will crash. For example : $ab$cd$efxyz becomes $$ab$$cd$$efxyz. This is due to caveats with docker-compose string interpolation system.

Troubleshoot

Should you encounter any issue running Erin, please refer to the following common problems that may occur.

If none of these matches your case, feel free to open an issue.

Erin is unreachable over HTTP / HTTPS

Erin sits on top of a Caddy web server.

As a result :

You may be able to better troubleshoot the issue by reading your container logs.
You can check the official Caddy documentation regarding addresses.
You can check the official Caddy documentation regarding HTTPS.

Other than that, please make sure that the following requirements are met :

If Erin runs as a standalone application without proxy :
- Make sure your server / firewall accepts incoming connections on Erin's port.
- Make sure your DNS configuration is correct. (Usually, such record should suffice : A erin XXX.XXX.XXX.XXX for https://erin.your-server-tld)
- Make sure your .env file is well configured according to the Configuration section.
If Erin runs inside Docker / behind a proxy :
- Perform the previous (standalone) verifications first.
- Make sure that PUBLIC_URL is well set in .env.
- Check your proxy forwarding rules.
- Check your Docker networking setup.

In any case, the crucial part is Configuration and reading the official Caddy documentation.

Erin says that no video was found on my server

For Erin to serve your video files, those must respect the following req

Erin

Install / Use

README