How-To's

Here are some examples of configuration:

How to enable WebAuthn / Passkey authentication?

You must enter the username on the login page if you are using a security key (also known as non-resident key in the WebAuthn protocol). This is not required for Passkeys which are discoverable credentials stored in the platform secure enclave, or in a trusted platform module (TPM).

Use a Unix socket for Postgresql

If you would like to connect via a Unix socket to Postgresql, set the parameter host=/path/to/socket/folder.

Example:

export DATABASE_URL="user=postgres password=postgres dbname=miniflux2 sslmode=disable host=/path/to/socket/folder"
./miniflux

How to run Miniflux on port 443 or 80

Ports less than 1024 are reserved for privileged users. If you have installed Miniflux with the RPM or Debian package, no further action is required. Systemd runs the process as the miniflux user with CAP_NET_BIND_SERVICE capability.

If you are not using systemd and want to give Miniflux the ability to bind to privileged ports as a non-root user, add the capability CAP_NET_BIND_SERVICE to the binary:

setcap cap_net_bind_service=+ep /usr/bin/miniflux

Check that the capability is added:

getcap /usr/bin/miniflux
/usr/bin/miniflux = cap_net_bind_service+ep

Note that you will have to do this operation each time you upgrade Miniflux.

Reverse-Proxy Configuration

You can use the reverse-proxy software of your choice, here an example with Nginx:

server {
    server_name     my.domain.tld;
    listen          80;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_redirect 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_set_header X-Forwarded-Proto $scheme;
    }
}

This example assumes that you are running the Miniflux daemon on 127.0.0.1:8080.

Reverse-Proxy with a subfolder

Since version 2.0.2, you can host your Miniflux instance under a subfolder.

You must define the environment variable BASE_URL for Miniflux, for example:

export BASE_URL=http://example.org/rss/

Nginx Example

server {
    server_name     my.domain.tld;
    listen          80;

    location /rss/ {
        proxy_pass http://127.0.0.1:8080/rss/;
        proxy_redirect 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_set_header X-Forwarded-Proto $scheme;
    }
}

Alternative Nginx Configuration

server {
    server_name     my.domain.tld;
    listen          80;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_redirect 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_set_header X-Forwarded-Proto $scheme;
    }
}

This example assumes that you are running the Miniflux daemon on 127.0.0.1:8080.

Now you can access your Miniflux instance at http://example.org/rss/. In this configuration, cookies are using the path /rss.

Apache 2.4 Example

This configuration assumes the same base-url as the nginx-example.

ProxyRequests Off
<Proxy *>
    Order allow,deny
    Allow from all
</Proxy>

<Location "/rss/">
    ProxyPreserveHost On
    ProxyPass http://127.0.0.1:8080/rss/
    ProxyPassReverse http://127.0.0.1:8080/rss/
</Location>

Place this snippet inside your vhosts config, needed modules: mod_proxy and mod_proxy_http.

Reverse-Proxy with a Unix socket

If you prefer to use a Unix socket, change the environment variable LISTEN_ADDR to the path of your socket.

Configure Miniflux to use a Unix socket:

LISTEN_ADDR=/run/miniflux/miniflux.sock

The socket folder must be writeable by the miniflux user:

sudo mkdir /run/miniflux
sudo chown miniflux: /run/miniflux

Example with Nginx as reverse-proxy:

server {
    server_name     my.domain.tld;
    listen          80;

    location / {
        proxy_pass  http://unix:/run/miniflux/miniflux.sock;
        proxy_redirect 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_set_header X-Forwarded-Proto $scheme;
    }
}

Systemd Socket Activation

This feature is experimental.

In this example, we are going to expose Miniflux on port 80 via Systemd.

Miniflux will be started by systemd at boot or on-demand. The process is running under an unprivileged user miniflux and we load the environment variables from /etc/miniflux.conf.

Create a file /etc/systemd/system/miniflux.socket:

[Unit]
Description=Miniflux Socket

[Socket]
NoDelay=true

# Listen on port 80.
# To use a unix socket, define the absolute path here.
ListenStream=80

[Install]
WantedBy=sockets.target

Create a file /etc/systemd/system/miniflux.service:

[Unit]
Description=Miniflux Service
Requires=miniflux.socket

[Service]
ExecStart=/usr/bin/miniflux
EnvironmentFile=/etc/miniflux.conf
User=miniflux
NonBlocking=true

[Install]
WantedBy=multi-user.target

Enable this:

sudo systemctl enable miniflux.socket
sudo systemctl enable miniflux.service

Tell systemd to listen on port 80 for us:

sudo systemctl start miniflux.socket

If you go to http://127.0.0.1/, systemd will start the Miniflux service automatically.

If you watch the logs with journalctl -u miniflux.service, you will see [INFO] Listening on systemd socket.

Let's Encrypt Configuration

You could use Let’s Encrypt to manage the SSL certificate automatically and activate HTTP/2.

export CERT_DOMAIN=my.domain.tld
miniflux
Miniflux supports http-01 challenge since the version 2.0.2.

Manual HTTPS Configuration

Here an example to generate a self-signed certificate:

# Generate the private key:
openssl genrsa -out server.key 2048
openssl ecparam -genkey -name secp384r1 -out server.key

# Generate the certificate:
openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650

Start the server like this:

# Configure the environment variables:
export CERT_FILE=/path/to/server.crt
export KEY_FILE=/path/to/server.key
export LISTEN_ADDR=":https"

# Start the server:
miniflux

Then you can access to your server by using an encrypted connection with the HTTP/2 protocol.

OAuth2 and OpenID Connect Authentication

OAuth2 allows you to sign in with an external provider.

Google

  1. Create a new project in Google Console
  2. Create a new OAuth2 client
  3. Set an authorized redirect URL, for example https://my.domain.tld/oauth2/google/callback
  4. Define the OAuth2 environment variables and start the process
OAUTH2_PROVIDER=google
OAUTH2_CLIENT_ID=replace_me
OAUTH2_CLIENT_SECRET=replace_me
OAUTH2_REDIRECT_URL=https://miniflux.example.org/oauth2/google/callback

Now from the settings page, you can link your existing user to your Google account.

If you would like to authorize anyone to create a user account, you must set OAUTH2_USER_CREATION=1. Since Google do not have the concept of username, the email address is used as username.

OpenID Connect

  1. Create a client in your OpenID Connect Provider, for example Keycloak
  2. Set Access Type confidental
  3. Set Client ID, for example miniflux
  4. Set valid Redirect URI, for example https://miniflux.example.org/oauth2/oidc/callback
  5. Set valid Web Origins, for example https://miniflux.example.org/oauth2/oidc/redirect
  6. Define the OAuth2 environment variables and start the process
OAUTH2_PROVIDER=oidc
OAUTH2_CLIENT_ID=replace_me
OAUTH2_CLIENT_SECRET=replace_me
OAUTH2_REDIRECT_URL=https://miniflux.example.org/oauth2/oidc/callback
OAUTH2_OIDC_DISCOVERY_ENDPOINT=https://my.oidc.provider.tld/auth/realms/id

You can use the OpenID Connect integration with different providers.

Note that the OIDC library automatically appends the .well-known/openid-configuration, this part has to be removed from the URL when setting OAUTH2_OIDC_DISCOVERY_ENDPOINT.

For example, Authentik discovery endpoint is https://authentik.example.org/application/o/miniflux/.well-known/openid-configuration and the OAUTH2_OIDC_DISCOVERY_ENDPOINT config option should be https://authentik.example.org/application/o/miniflux/ (note the trailing /).

Authentik

Example of Miniflux configuration with Authentik:

OAUTH2_PROVIDER=oidc
OAUTH2_CLIENT_ID=replace_me
OAUTH2_CLIENT_SECRET=replace_me
OAUTH2_REDIRECT_URL=https://miniflux.example.org/oauth2/oidc/callback
# Authentik discovery endpoint is https://authentik.example.org/application/o/miniflux/.well-known/openid-configuration
OAUTH2_OIDC_DISCOVERY_ENDPOINT=https://authentik.example.org/application/o/miniflux/
OAUTH2_USER_CREATION=1

Kanidm

Example of Miniflux configuration with Kanidm:

OAUTH2_PROVIDER=oidc
OAUTH2_CLIENT_ID=replace_me
OAUTH2_CLIENT_SECRET=replace_me
OAUTH2_REDIRECT_URL=https://miniflux.example.org/oauth2/oidc/callback
OAUTH2_OIDC_DISCOVERY_ENDPOINT=https://kanidm.example.org/oauth2/openid/miniflux
OAUTH2_USER_CREATION=1

Zitadel

Example of Miniflux configuration with Zitadel:

OAUTH2_PROVIDER=oidc
OAUTH2_CLIENT_ID=replace_me
OAUTH2_REDIRECT_URL=https://miniflux.example.org/oauth2/oidc/callback
OAUTH2_OIDC_DISCOVERY_ENDPOINT=https://zitadel.example.org
OAUTH2_USER_CREATION=1

Deploy Miniflux on Heroku

Since the version 2.0.6, you can deploy Miniflux on Heroku in few seconds.

Defines the environment variables to configure the application:

# Creates all tables in the database.
heroku config:set RUN_MIGRATIONS=1

# Creates the first user.
heroku config:set CREATE_ADMIN=1
heroku config:set ADMIN_USERNAME=admin
heroku config:set ADMIN_PASSWORD=test123

Then, deploy the application to Heroku:

git push heroku master

Once the application is deployed successfully, you don’t need these variables anymore:

heroku config:unset CREATE_ADMIN
heroku config:unset ADMIN_USERNAME
heroku config:unset ADMIN_PASSWORD

Deploy Miniflux on Google App Engine

If you have experience with Terraform and want a setup that works out of the box, consider using this Terraform module. Alternatively, you can follow these instructions:

runtime: go111
env_variables:
    CLOUDSQL_CONNECTION_NAME: INSTANCE_CONNECTION_NAME
    CLOUDSQL_USER: replace-me
    CLOUDSQL_PASSWORD: top-secret

    CREATE_ADMIN: 1
    ADMIN_USERNAME: foobar
    ADMIN_PASSWORD: test123
    RUN_MIGRATIONS: 1
    DATABASE_URL: "user=replace-me password=top-secret host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=miniflux"

Replace the values according to your project configuration. As you can see, the database connection is made over a Unix socket on App Engine.

Last step, deploy your application:

gcloud app deploy

Refer to Google Cloud documentation for more details:

Running Miniflux on Google App Engine should work but it's considered experimental.