Setting up¶

Before starting HPX it is recommended to go through all the available settings that configure how HPX should be running. You can see the available settings here.

To use these settings, you create a configuration file named config.yaml in the root directory of HPX.

You can generate an example configuration file with all settings listed with their default values if you run this command: ./happypandax --gen-config.

Most of these settings can also be configured from a HPX client.

Starting¶

You can start up HPX in two ways with the executables named happypandax and happypandax_gui.

The happypandax_gui executable is mostly just a GUI wrapper around happypandax to provide a user-friendly way of starting HPX.

Before starting, you can also see the available command-line arguments by supplying the --help argument to the happypandax executable on the cmd/terminal: ./happypandax --help. You could also refer to Command-Line Arguments.

To start the server (and the webclient with it) you just start one of the two executables.

Migrating from HappyPanda¶

In the HPX root folder, you can find a command-line tool named HPtoHPX to help convert your HP database. See available arguments by supplying the --help argument to the executable: ./HPtoHPX --help.

Convert your HP database like this: ./HPtoHPX "path/to/old/file.db" "data/happypanda.db"

Alternatively, you can also use the GUI wrapper happypandax_gui which provides a user-friendly way of doing it.

Using¶

After starting HPX you can start using it right away by opening up your browser and going to localhost:7008 (replace ``7008`` with whatever port you chose the webclient server to listen on)

What else you could do is look for another client to use HPX with. They can come in all forms (mobile apps, pc software, etc.) as long as someone builds it. If you’re interested in building a client to work with HPX, head over to Creating frontends for an introduction.

Since a HPX client cannot function without the server running, it is a good idea to always leave the HPX server running in the background.

Be careful about plugins¶

A plugin can not do anything before it has been installed.

Plugins have as much power as HPX once installed.

If you give HPX elevated privileges when running, plugins will also have this privilege but not before they have been installed. Know that, inherently, HappyPanda X does not need elevated privileges.

Some plugins may also cause unwanted effects towards your system or database. That is why care should be taken when wanting to use a plugin. Only use those you trust, and also don’t just blindly trust a plugin. Backing up your HPX database before installing a plugin is recommended.

This all sounds scary and you might even question why even use plugins. HPX tries its best to minimize some of these issues. As long as plugin developers follow the guidelines and write safe code then everything should be okay.

The HappyPanda X Plugin Repo houses plugins that have been checked and are for the most part safe to use. If you’re a plugin developer and want your plugin in there, just submit a PR.

Users¶

HPX creates a default super-user called default with no password. This user is enabled by default. If you’re planning on having multiple people accessing your HPX server, or you want to access the server from a remote origin over the internet, it is best you disable this user. Disable it with the setting server.disable_default_user.

Additionally, you may also want to disallow people accessing the server without logging in with the settings server.allow_guests and server.require_auth.

To create and delete users, see the command-line args user --help or use the GUI.

TLS/SSL Support¶

To enable SSL connections see the setting server.enable_ssl. You can choose to only enable SSL for one of the components by setting the value to either server or web. Set the value to true to enable for both.

Provide your certification and private key files with the settings server.server_cert and server.web_cert. If your private key and certificate is stored in the same file, you only need to set certfile and can ignore keyfile.

You can also choose to not provide any certfiles at all, in which case HPX will proceed to create a self-signed certificate for your personal use. These files can be found at [HPX]/data/certs/. happypandax.crt is the certificate, happypandax.key is the private key and happypandax.pem is the combined version of the two. To get other clients to accept your server with the self-signed certificate, provide them with the happypandax.crt file.

When using the self-signed certificate, browsers will complain about an unsecure connection. Since you’re using HPX for personal reasons and trust yourself (i hope so), you can go ahead and allow the connection by adding an exception.

Private network¶

Exposing HPX to your private network will allow any device connected to your home network to access HPX. This means that you can enjoy your collection on HPX not only from your computer but also from your tablet, phone, etc. as long as they are connected to your home network either through Wi-Fi or LAN.

When starting HPX, set the two settings server.host and server.host_web to 0.0.0.0. This means that the server should listen on all interfaces. We can also set the ports with the settings server.port and server.port_web, but we’ll leave them to their default values.

The next step is to allow connections on the chosen ports through your firewall.

Public network¶

Exposing HPX to the public network will allow you to access HPX from any device connected to the internet.

Reverse Proxy¶

You might wanna use a reverse proxy such as NGINX in front of HPX.

server {
    listen 80;
    listen [::]:80;
    server_name example.me www.example.me;
    charset utf-8;

    # for websocket
    location /websocket {
        proxy_pass http://localhost:7008/websocket;
        proxy_redirect off;
        proxy_buffering off;

    proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }

    location / {
        proxy_pass http://localhost:7008;
    proxy_redirect off;
        gzip off;

        proxy_read_timeout  300;
    proxy_connect_timeout   300;

    proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }

}