Hyve
Expose and consume your hydrus media via HTTP API
Install / Use
/learn @imtbl/HyveREADME
Expose and consume your hydrus media via HTTP API
Unmaintained: hyve is no longer maintained. Due to the limitations and annoyances of hydrus server, I would recommend "abusing" a hydrus client instance as a server instead (this can also be done on headless machines, e.g., containerized via [suika/hydrus][hydrus-docker]), which allows you to use the [hydrus client API][hydrus-client-api]. And instead of running hyve you can then access your media over the web via clients like [Hydrus Web][hydrus-web] or [Hydroid][hydroid]. hyve still does some things that you (as of January 2021) can not yet do via client API, so if you do decide to continue using it regardless of it being unmaintained, I recommend you fork it and keep the dependencies up-to-date (to protect against potential vulnerabilities).
hyve is an application that allows you to serve [hydrus][hydrus] media over an HTTP API. It can connect to either hydrus client or server. A web-based, [booru][booru]-like client that consumes the API is also included.
As a rough overview, hyve currently has the following features:
- The ability to connect to either hydrus client or hydrus server
- A straightforward HTTP API, including:
- Comprehensive options to search and sort your files and tags
- Optional authentication and simple user management, allowing you to run hyve in either a public or private manner
- A modern web client that makes use of the API's full feature set and comes
with:
- An easy to use interface that is optimized for both desktop and mobile devices
- Direct support for common image and video formats on the web; non-supported files can be downloaded and viewed locally
- Built-in user registration, login and actions like changing username or password or deleting the user altogether
- The ability to save options like tag colors and default sorting methods on a per-client basis, allowing you to have different settings in each browser
- Basic web app features that allow you to add the client to the home screen of your smart device and use it just like a native app
hyve does not allow you to modify or manage your hydrus media in any way, it simply provides a different way to view them.
Table of contents
Install
The recommended way to run is via [Docker][docker]. Basic instructions on how to run without it are also provided.
Installing with Docker
To install hyve for running with Docker, you can simply pull the prebuilt image from [Docker Hub][docker-hub]:
user@local:~$ docker pull mtbl/hyve
Alternatively, you can also build the image yourself. The user that is used
inside the container has UID 1000 and GID 1000 by default. You can adjust
this (e.g., to match your host UID/GID) by providing the arguments USER_ID
and GROUP_ID when making a build.
Installing without Docker
To install without Docker, you can simply clone the repository and install dependencies:
user@local:~$ git clone https://github.com/imtbl/hyve.git
user@local:~$ cd hyve
user@local:hyve$ yarn && yarn bootstrap
Dependencies
- [hydrus][hydrus] (either the client or the server, depending on what you want to connect to)
- [Docker][docker] (when running with Docker)
- [Node.js][node-js] (when running without Docker)
- [Yarn][yarn] (when running without Docker)
hyve should work with both the latest LTS and the latest stable version of Node.js. If you encounter any issues with either of those versions when running without Docker, please [let me know][issues].
Updating
hyve follows [semantic versioning][semantic-versioning] and any breaking
changes that require additional attention will be released under a new major
version (e.g., 2.0.0). Minor version updates (e.g., 1.1.0 or 1.2.0) are
therefore always safe to simply install.
When necessary, this section will be expanded with upgrade guides for new major versions.
Updating with Docker
Simply pull the latest Docker image to update:
user@local:~$ docker pull mtbl/hyve
Updating without Docker
If you have installed via cloning the repository, you can update via Git:
user@local:hyve$ git pull
user@local:hyve$ yarn && yarn bootstrap
user@local:hyve$ cd services/server
user@local:hyve/services/server$ yarn migrate
Upgrading from 2.x.x to 3.x.x
3.0.0 has introduced no breaking API changes and merely reflects the switch
to a new license (AGPLv3).
Upgrading from 1.x.x to 2.x.x
2.0.0 has introduced the ability to (optionally) connect to hydrus client
instead of hydrus server.
Aside from renaming services/sync to services/sync-server (which you might
need to adjust in any start scripts you might have set up when running without
Docker), a few environment variables have been added, so you can simply compare
with your current configuration and make additions/adjustments where necessary.
Usage
hyve consists of three different services:
- Sync: used to create a modified copy of the hydrus databases that is
optimized for hyve's purposes and allows for searching and sorting options
that would otherwise not be possible
- There are two variants, one for hydrus client and one for hydrus server
- Server: the server component of hyve that provides the HTTP API
- Web: the web-based client that connects to the HTTP API
In general, you will probably want to run all three services, unless you plan to use a different client to connect to the HTTP API.
Depending on on your choice on you want what to connect to, you will also need to run either hydrus client or server. If you are considering using hyve, you are probably already familiar with the client. In that case, you can just continue using it as you normally would. If you want to set up a server (to connect hyve to that instead), you can find a guide for doing so [here][hydrus-server-help].
If you plan to expose the HTTP API outside your local network, it is heavily recommended to use HTTPS. To do this, you will likely want to set up a reverse proxy (I recommend [nginx][nginx]).
hyve uses a lock file called .sync-lock to prevent additional syncs from
running while one is already in progress. This file is located in the same
directory as hyve's content database. In some instances (e.g., shutdown during
a sync), this file might not be removed (causing it to become stale). In that
case, you may have to delete it manually before attempting to run the next
sync. When running with Docker, the lock file (should it exist at that point)
will automatically get removed during sync container startup for your
convenience (keep this in mind if you are sharing the same hyve content
database between multiple instances).
Running with Docker
To make running with Docker as easy as possible, a working [Docker Compose][docker-compose] example setup is provided. This setup also includes a [dockerized hydrus server][hydrus-server-docker] and stores the data inside a named volume (which you might want to adjust if you are a more experienced Docker user).
Running hyve with hydrus server might be preferable if you want to manage your media with a local hydrus client and are fine with pushing any files you want to use with hyve to hydrus server.
To get started with the example setup, simply duplicate
docker-compose.yml.server.example as docker-compose.yml, adjust the
variables in the environment section as described here.
In addition to the environment variables configuring the settings for the
respective service, also take note of the time zone set via TZ (for each
service). This is particularly important for the sync cron job to run at the
time you expect it to. The time zone has to be set in the
[tz database format][tz-database-time-zones].
Finally, start the containers:
user@local:hyve$ docker-compose up -d
Afterwards, proceed with the hydrus server setup, upload your files and tags to it and wait for the first sync to run. The HTTP API and the web client will be available under the configured URLs.
If you want to connect to hydrus client instead, you can have a look at
[this][hydrus-docker] for a dockerized version of hydrus client that you should
be able to run in combination with hyve. I have included a Docker Compose
example setup only containing the hyve services
(docker-compose.yml.client.example) that you will
