Installation with Docker

HoyoShip is published as the container image docker.io/doricodynamics/hoyoship for linux/amd64. Running it with Docker suits evaluation and single-host installations; for production, install HoyoShip on Kubernetes.

The registry is private. Log in with the credentials you received from support@doricod.com, then pull a release:

docker login docker.io
docker buildx imagetools inspect docker.io/doricodynamics/hoyoship:vX.Y.Z --format '{{.Manifest.Digest}}'

Each release has its own tag, vX.Y.Z; there is no moving tag such as latest (see Releases). The command above prints the release’s digest, sha256:<digest>. Use the image by tag and digest, docker.io/doricodynamics/hoyoship:vX.Y.Z@sha256:<digest>, as in the examples below, so that a later docker compose pull cannot change what runs. Moving to a new minor release requires the steps in the upgrade guide.

The image runs HoyoShip as the unprivileged user git (UID and GID 1000). It serves the web interface on port 3000 and runs its own SSH server on port 2222, and keeps all its data, including the configuration, in /var/lib/gitea.

Docker Compose

Create the data directories and give them to UID and GID 1000:

mkdir -p ./hoyoship ./postgres
sudo chown -R 1000:1000 ./hoyoship

Here is an example docker-compose file with a PostgreSQL database:

networks:
  hoyoship:
    external: false

services:
  server:
    image: docker.io/doricodynamics/hoyoship:vX.Y.Z@sha256:<digest>
    container_name: hoyoship
    user: 1000:1000
    environment:
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=hoyoshipdb
      - FORGEJO__database__USER=hoyoship
      - FORGEJO__database__PASSWD=hoyoship
    restart: always
    networks:
      - hoyoship
    volumes:
      - ./hoyoship:/var/lib/gitea
      - /etc/localtime:/etc/localtime:ro
    ports:
      - '3000:3000'
      - '2222:2222'
    depends_on:
      - db

  db:
    image: postgres:16
    restart: always
    environment:
      - POSTGRES_USER=hoyoship
      - POSTGRES_PASSWORD=hoyoship
      - POSTGRES_DB=hoyoshipdb
    networks:
      - hoyoship
    volumes:
      - ./postgres:/var/lib/postgresql/data

Replace the example passwords before you use the file. Start HoyoShip with docker compose up -d, then go to http://localhost:3000 in a browser to complete the configuration.

If the volume is not owned by UID and GID 1000, the container may not start.

To use MySQL instead, set FORGEJO__database__DB_TYPE=mysql and FORGEJO__database__HOST=db:3306, and run a mysql:8 service with the matching MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE and MYSQL_ROOT_PASSWORD. If no database is configured, HoyoShip uses SQLite, which is only suitable for evaluation. See Database Preparation.

SSH

SSH is published on port 2222 in the example above. To check that a key you added in HoyoShip works, run:

ssh -F /dev/null git@<address> -p 2222

If you publish SSH on another host port, set FORGEJO__server__SSH_PORT to that port so that clone URLs show it.

Configuration

The HoyoShip configuration is stored in the app.ini file as described in the Configuration Cheat Sheet. In the HoyoShip image it is /var/lib/gitea/custom/conf/app.ini, and it is automatically created if it does not exist already.

It is possible to add and modify configuration values by setting environment variables named in format FORGEJO__[SECTION]__[KEY]. The DEFAULT section of the configuration should be an empty string. For instance:

FORGEJO____APP_NAME=HoyoShip
FORGEJO__repository__ENABLE_PUSH_CREATE_USER=true

is equivalent to adding the following to app.ini:

APP_NAME=HoyoShip

[repository]
ENABLE_PUSH_CREATE_USER = true

Note

It is not possible to use environment variables to remove an existing value, it must be done by editing the app.ini file.

Note

In case you are in a SELinux environment check the audit logs if you are having issues with containers.

Hosting repository data on remote storage systems

You might also mount the data and repository folders on a remote drive such as a network-attached storage system. While there are a multitude of possible solutions, we will focus on a somewhat minimal setup with NFS here and explain what measures have to be taken in general so that the administrators can adapt this to their individual setup.

We begin to describe a possible setup and will try to highlight all important aspects which the administrator will have to consider if a different hosting environment is present. An important assumption for the HoyoShip image to make is to own the folders it writes into and reads from. This is naturally an issue since file-system permissions are a machine-local concept and don’t translate over the network easily.

We assume that a server with the hostname server is accessible which has a folder /repositories shared via NFS. Append an entry to your /etc/exports like

[...]
/repositories    *(rw,sync,all_squash,sec=sys,anonuid=1024,anongid=100)

Four aspects to consider:

• The folder is mounted as rw, meaning clients can both read and write in the folder.
• The folder is mounted as sync. This is NFS-specific but means that transactions block until they are finished. This is not essential but increases the robustness against file corruption
• The all_squash setting maps all file accesses to an anonymous user, meaning that both the files of a user with the UID of 1050 and 1051 are mapped to a single UID on the server.
• We set these anonymous (G/U)ID to explicit values on the server with anonuid=1024,anongid=100. Hence all files will be owned by a user with the UID 1024, belonging to a group 100. Make sure the UID is available and a group with that ID is present.

Effectively we are now able to write and create files and folders on the remote share. With the all_squash setting, we map all users to one user, hence all data writable by one user is writable by all users, implying all files have a drwxrwxrwx setting (abbreviated “0777 permissions”). We can also “fake-own” data, since all chown calls are now mapped to the anonymous user. This is an important behaviour. We now mount this folder on the client which will host HoyoShip to a folder /mnt/repositories…

sudo mount -o hard,timeo=10,retry=10,vers=4.1 server:/repositories /mnt/repositories/

… and create a folder

mkdir /mnt/repositories/data

To consider in the NFS client setup is the hard setting, blocking all file operations if the share is not available. This prevents state changes in the repository which could potentially corrupt the repository data and is an NFS-specific setting.

The HoyoShip image runs its own SSH server. A possible entry for a docker-compose file would look like this (shown as a diff-like view to the example above):

services:
  server:
    image: docker.io/doricodynamics/hoyoship:vX.Y.Z@sha256:<digest>
    container_name: hoyoship
-   user: 1000:1000
+   user: "1024:100"
    volumes:
-      - ./hoyoship:/var/lib/gitea
+      - /mnt/repositories/data:/var/lib/gitea
      - /etc/localtime:/etc/localtime:ro

This will write the configuration and all other data into the data folder. Make sure that 1024 and 100 match the anonuid and anongid setting in the NFS server setting here such that the HoyoShip user sees files and folders with the same UID and GID in the respective folders and thus identifies itself as the sole owner of the folder structure.

Because the image embeds its own SSH server instead of openssh, SSH keys stored on the share still work with 0777 permissions. openssh would refuse them, and the all_squash setup, which is needed for a correct ownership mechanic on the server, does not allow changing those permissions.

Note, that this setup is simple and does not necessarily reflect the reality of your network. User mapping and ownership could be streamlined better with Kerberos, but that is out of the scope of this guide.