Psono Documentation

# Install Favicon server

Installation instruction for the Psono favicon server. You can setup an own favicon server as outlined below or use our hosted version by configuring FAVICON_SERVICE_URL: https://favicon.psono.com/v1/icon/.

# Preamble

At this point we assume that you already have a Psono server running, ready to accept connections. This guide will explain how you can setup a private favicon server which will download and cache favicons for websites, so that they can be displayed in the webclient. We assume that we want to host Psono behind the same Domain and reverse proxy as the regular server.

We assume that you want to use:

  • https://psono.example.com to host Psono
  • https://psono.example.com/favicon/ to proxy all requests to the

# Setup favicon server

  1. Configure favicon URL

    Clients need to know the URL to the favicon server.:

    FAVICON_SERVICE_URL: 'https://psono.example.com/favicon/'

    TIP

    Don't forget to restart the server afterward.

  2. Create local storage location

    The favicon server will cache all favicons on disc that you may want to preserve across updates / container restarts.

    mkdir /opt/psono-favicon-icon

  3. Run the favicon server container

    docker run --name psono-favicon server \
    --sysctl net.core.somaxconn=65535 \
    -v /opt/psono-favicon-icon:/root/icon \
    -d --restart=unless-stopped -p 10400:80 esaqa/favicon:latest

    This will start the Psono favicon server on port 10400. If you open now http://your-ip:10400/v1/healthcheck/ you should see something like this:

    {"time_sync":{"healthy":true},"_info":{"ip":"..."}}

    If you don't, please make sure no firewall is blocking your request.

  4. Modify nginx config

    Add the following part to the server context.

    location /favicon {
    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_set_header        X-Forwarded-Proto $scheme;
    proxy_hide_header       Access-Control-Allow-Origin;

    rewrite ^/favicon/(.*) /v1/icon/$1 break;

    proxy_pass          http://localhost:10400;
    gzip on;
}

  5. (option) Configure Content-Security-Policy

    If you use a separate domain (e.g. https://favicon.example.com), you need to modify your server's Content-Security-Policy which will instruct your user's browsers to allow connections to the favicon server later from the origin of your webclient. As such add e.g. https://favicon.example.com to the img-src. The corresponding part should look like this:

    ...
add_header Content-Security-Policy "default-src 'none';  manifest-src 'self'; connect-src 'self' https://static.psono.com https://api.pwnedpasswords.com https://storage.googleapis.com https://*.digitaloceanspaces.com https://*.blob.core.windows.net https://*.s3.amazonaws.com; font-src 'self'; img-src 'self' https://favicon.example.com https://favicon.psono.com data:; script-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'self'; child-src 'self'";
...

    TIP

    Don't forget to restart the nginx afterward.

  6. Validate

    • Login to the webclient and check that you can now see favicons. Clients may need to logout and login to get the favicon server url and use the service.
    • Check that /opt/psono-favicon-icon contains now icons.

# Note: Installation behind Firewall

If you have put your installation behind a firewall, you have to whitelist some ports / adjust some settings, that all features work:

  • Incoming TCP connection (usually 443) from clients to favicon servers.
  • Outgoing TCP connection (usually 80 & 443) from favicon servers to internet and other websites that it should fetch favicons for.
  • Outgoing TCP / UDP 123 connection to time.google.com: Favicon requires a synced time for various reasons (e.g. Throttling) Therefore it has a healthcheck, to compare the local time to a time server (by default time.google.com). You can specify your own timeserver in the settings.yaml with the "TIME_SERVER" parameter. If you are confident that your server always has the correct time you can also disable the healthcheck with "HEALTHCHECK_TIME_SYNC_ENABLED: False".

← Audit Log →