Add feature to add custom css/js instead of overwriting all content (#248)

This commit is contained in:
Marc Bulling
2025-05-19 20:43:18 +02:00
committed by GitHub
parent e41c4bd1ff
commit d4bfad90c3
26 changed files with 357 additions and 190 deletions

View File

@@ -363,10 +363,12 @@ If you are using a Docker image, this has to be done by starting a container wit
Customising
********************************
By default, all files are included in the executable. If you want to change the layout (e.g. add your company logo or change the app name etc.), follow these steps:
If you want to change the layout (e.g. add your company logo or add/disable certain features), follow these steps:
1. Download the source code for the Gokapi version you are using. It is either attached to the specific release `on Github <https://github.com/Forceu/Gokapi/releases>`_ or you can clone the repository and checkout the tag for the specific version.
2. Copy either the folder ``static``, ``templates`` or both from the ``internal/webserver/web`` folder to the directory where the executable is located (if you are using Docker, mount the folders into the the ``/app/`` directory, e.g. ``/app/templates``).
3. Make changes to the folders. ``static`` contains images, CSS files and JavaScript. ``templates`` contains the HTML code.
4. Restart the server. If the folders exist, the server will use the local files instead of the embedded files.
5. Optional: To embed the files permanently, copy the modified files back to the original folders and recompile with ``go generate ./...`` and then ``go build github.com/forceu/gokapi/cmd/gokapi``.
1. Create a new folder named ``custom`` where your executable is. When using Docker, mount a new folder to ``/app/custom/``. Any file in this directory will be publicly available in the sub-URL ``/custom/``.
2. To have custom CSS included, create a file in the folder named ``custom.css``. The CSS will be applied to all pages.
3. To have custom JavaScript included, create the file ``public.js`` for all public pages and/or ``admin.js`` for all admin-related pages. Please note that the ``admin.js`` will be readable to all users.
4. In order to prevent caching issues, you can version your files by creating the file ``version.txt`` with a version number.
5. Restart the server. If the folders exist, the server will now add the local files.
Optional: If you require further changes or want to embedded the changes permanently, you can clone the source code and then modify the templates in ``internal/webserver/web/templates``. Afterwards run ``make`` to build a new binary with these changes.

View File

@@ -18,7 +18,7 @@
# -- Project information -----------------------------------------------------
project = 'Gokapi Documentation'
copyright = '2024, Marc Ole Bulling'
copyright = '2025, Marc Ole Bulling'
author = 'Marc Ole Bulling'
# The full version, including alpha/beta/rc tags
@@ -53,7 +53,9 @@ html_theme = "sphinx_rtd_theme"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['']
html_static_path = ['static']
html_css_files = ['custom.css']
master_doc = 'index'
#autosectionlabel_prefix_document = True

View File

@@ -24,7 +24,7 @@ Nginx Configuration
ssl_certificate /your/certificate/fullchain.pem;
ssl_certificate_key /your/certificate/privkey.pem;
client_max_body_size 500M;
client_max_body_size 200M;
client_body_buffer_size 128k;
server_name your.server.url;
@@ -123,46 +123,40 @@ See the `Authelia documentation <https://www.authelia.com/configuration/identity
* Set ``authorization_policy`` to ``two_factor`` to use OTP or a hardware key.
* If ``consent_mode`` is ``pre-configured``, the user has the option to remember consent. That way you can use a lower ``Recheck identity`` interval in Gokapi. Logout through the Gokapi interface will not be possible anymore, unless the user logs out their Authelia account. If the option is set to ``explicit``, the user always has to grant the permission after the ``Recheck identity`` interval has passed
* ``scopes`` may exclude ``email`` and ``groups`` if these are not required for authentication, e.g. if all users registered with Authelia may access Gokapi.
* ``scopes`` may exclude ``groups`` if these are not required for authentication, e.g. if all users registered with Authelia may access Gokapi.
* Make sure ``redirect_uris`` is set to the correct value
Gokapi Configuration
""""""""""""""""""""""
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Gokapi Configuration | Input | Example |
+==========================+===========================================================+=========================================+
| Provider URL | URL to Authelia Server | \https://auth.autheliaserver.com |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Client ID | Client ID provided in config | gokapi-dev |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Client Secret | Client secret provided in config | AhXeV7_EXAMPLE_KEY |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Recheck identity | If mode is ``pre-configured``, use a low interval | 12 hours |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Restrict to user | Check this, if only certain users shall be allowed to | checked |
| | | |
| | access Gokapi admin menu | |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Scope identifier (user) | Use a scope that is unique to the user, e.g. the username | email |
| | | |
| | or the email | |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Authorised users | Enter all users, separated by semicolon | \*\@company.com;admin\@othercompany.com |
| | | |
| | ``*`` can be used as a wildcard | |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Restrict to group | Check this, if only users from certain groups shall be | checked |
| | | |
| | allowed to access Gokapi admin menu | |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Scope identifier (group) | Use a scope that lists the user's groups | groups |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
| Authorised groups | Enter all groups, separated by semicolon | dev;admins;gokapi-* |
| | | |
| | ``*`` can be used as a wildcard | |
+--------------------------+-----------------------------------------------------------+-----------------------------------------+
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Gokapi Configuration | Input | Example |
+===========================+=============================================================+=========================================+
| Provider URL | URL to Authelia Server | \https://auth.autheliaserver.com |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Client ID | Client ID provided in config | gokapi-dev |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Client Secret | Client secret provided in config | AhXeV7_EXAMPLE_KEY |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Admin email address | The email address for the super-admin | gokapi@example.com |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Recheck identity | If mode is ``pre-configured``, use a low interval | 12 hours |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Restrict to group | Check this, if only users from certain groups shall be | checked |
| | | |
| | allowed to access Gokapi admin menu | |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Scope identifier (group) | Use a scope that lists the user's groups | groups |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Authorised groups | Enter all groups, separated by semicolon | dev;admins;gokapi-* |
| | | |
| | ``*`` can be used as a wildcard | |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
| Only allow existing users | Check this, if you do not want authenticated users to | unchecked |
| | | |
| | automatically create a new account or restore a deleted one | |
+---------------------------+-------------------------------------------------------------+-----------------------------------------+
.. _oidcconfig_keycloak:
@@ -230,39 +224,33 @@ Addding a scope for exposing groups (optional)
Gokapi Configuration
""""""""""""""""""""""
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Gokapi Configuration | Input | Example |
+==========================+=======================================================================+============================================+
| Provider URL | URL to Keycloak realm | \http://keycloak.server.com/realms/master |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Client ID | Client ID provided | gokapi-dev |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Client Secret | Client secret provided | AhXeV7_EXAMPLE_KEY |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Recheck identity | If open ``Consent required`` is disabled, use a low interval | 12 hours |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Restrict to user | Check this, if only certain users shall be allowed to | checked |
| | | |
| | access Gokapi admin menu | |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Scope identifier (user) | Use a scope that is unique to the user, e.g. the username | email |
| | | |
| | or the email | |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Authorised users | Enter all users, separated by semicolon | \*\@company.com;admin\@othercompany.com |
| | | |
| | ``*`` can be used as a wildcard | |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Restrict to group | Check this, if only users from certain groups shall be | checked |
| | | |
| | allowed to access Gokapi admin menu | |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Scope identifier (group) | Use a scope that lists the user's groups | groups |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Authorised groups | Enter all groups, separated by semicolon | dev;admins;gokapi-* |
| | | |
| | ``*`` can be used as a wildcard | |
+--------------------------+-----------------------------------------------------------------------+--------------------------------------------+
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Gokapi Configuration | Input | Example |
+===========================+=======================================================================+============================================+
| Provider URL | URL to Keycloak realm | \http://keycloak.server.com/realms/master |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Client ID | Client ID provided | gokapi-dev |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Client Secret | Client secret provided | AhXeV7_EXAMPLE_KEY |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Recheck identity | If open ``Consent required`` is disabled, use a low interval | 12 hours |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Admin email address | The email address for the super-admin | gokapi@example.com |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Restrict to group | Check this, if only users from certain groups shall be | checked |
| | | |
| | allowed to access Gokapi admin menu | |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Scope identifier (group) | Use a scope that lists the user's groups | groups |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Authorised groups | Enter all groups, separated by semicolon | dev;admins;gokapi-* |
| | | |
| | ``*`` can be used as a wildcard | |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
| Only allow existing users | Check this, if you do not want authenticated users to | unchecked |
| | | |
| | automatically create a new account or restore a deleted one | |
+---------------------------+-----------------------------------------------------------------------+--------------------------------------------+
.. note::
@@ -293,28 +281,25 @@ Server Configuration
Gokapi Configuration
""""""""""""""""""""""
+-------------------------+--------------------------------------------------+----------------------------------+
| Gokapi Configuration | Input | Example |
+=========================+==================================================+==================================+
| Provider URL | \https://accounts.google.com | \https://accounts.google.com |
+-------------------------+--------------------------------------------------+----------------------------------+
| Client ID | Client ID provided | XXX.apps.googleusercontent.com |
+-------------------------+--------------------------------------------------+----------------------------------+
| Client Secret | Client secret provided | AhXeV7_EXAMPLE_KEY |
+-------------------------+--------------------------------------------------+----------------------------------+
| Recheck identity | Use a low interval | 12 hours |
+-------------------------+--------------------------------------------------+----------------------------------+
| Restrict to user | Check this, otherwise any Google user can access | checked |
| | | |
| | | |
| | your Gokapi admin menu | |
+-------------------------+--------------------------------------------------+----------------------------------+
| Scope identifier (user) | email | email |
+-------------------------+--------------------------------------------------+----------------------------------+
| Authorised users | Enter all users, separated by semicolon | user\@gmail.com;admin\@gmail.com |
+-------------------------+--------------------------------------------------+----------------------------------+
| Restrict to group | Unsupported | unchecked |
+-------------------------+--------------------------------------------------+----------------------------------+
+---------------------------+-------------------------------------------------------------+----------------------------------+
| Gokapi Configuration | Input | Example |
+===========================+=============================================================+==================================+
| Provider URL | \https://accounts.google.com | \https://accounts.google.com |
+---------------------------+-------------------------------------------------------------+----------------------------------+
| Client ID | Client ID provided | XXX.apps.googleusercontent.com |
+---------------------------+-------------------------------------------------------------+----------------------------------+
| Client Secret | Client secret provided | AhXeV7_EXAMPLE_KEY |
+---------------------------+-------------------------------------------------------------+----------------------------------+
| Recheck identity | Use a low interval | 12 hours |
+---------------------------+-------------------------------------------------------------+----------------------------------+
| Admin email address | The email address for the super-admin | gokapi@example.com |
+---------------------------+-------------------------------------------------------------+----------------------------------+
| Restrict to group | Unsupported | unchecked |
+---------------------------+-------------------------------------------------------------+----------------------------------+
| Only allow existing users | Check this, if you do not want authenticated users to | unchecked |
| | | |
| | automatically create a new account or restore a deleted one | |
+---------------------------+-------------------------------------------------------------+----------------------------------+
@@ -359,18 +344,22 @@ Optional: Restricting Gokapi to specific users or groups:
Gokapi Configuration
""""""""""""""""""""""
+----------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Gokapi Configuration | Input | Example |
+======================+===================================================================+=============================================================================+
| Provider URL | \https://login.microsoftonline.com/REALM/v2.0/, replace ``REALM`` | \https://login.microsoftonline.com/abcdef-1234-4678-9540-abcdefabcdef/v2.0/ |
+----------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Client ID | Client ID provided | 11111122222-4444-55555-66666-abcdefabcdef |
+----------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Client Secret | Client secret provided | ach5sho3Ru-Heop7aMaez-example |
+----------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Recheck identity | Use a low interval | 12 hours |
+----------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Restrict to user | Unsupported | unchecked |
+----------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Restrict to group | Unsupported | unchecked |
+----------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Gokapi Configuration | Input | Example |
+===========================+===================================================================+=============================================================================+
| Provider URL | \https://login.microsoftonline.com/REALM/v2.0/, replace ``REALM`` | \https://login.microsoftonline.com/abcdef-1234-4678-9540-abcdefabcdef/v2.0/ |
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Client ID | Client ID provided | 11111122222-4444-55555-66666-abcdefabcdef |
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Client Secret | Client secret provided | ach5sho3Ru-Heop7aMaez-example |
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Admin email address | The email address for the super-admin | gokapi@example.com |
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Recheck identity | Use a low interval | 12 hours |
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Restrict to group | Unsupported | unchecked |
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+
| Only allow existing users | Check this, if you do not want authenticated users to | checked |
| | | |
| | automatically create a new account or restore a deleted one | |
+---------------------------+-------------------------------------------------------------------+-----------------------------------------------------------------------------+

View File

@@ -117,6 +117,7 @@ The following configuration can be set:
- **Use SSL** Generates a self-signed SSL certificate (which can be replaced with a valid one). Select this if you are not running Gokapi behind a reverse proxy. Please note: Gokapi needs to be restarted in order to renew a certificate.
- **Save IP** If set, the IP address of the client requesting a download will be saved to the log file. This might not be GDPR compliant.
- **Include filename in download URL** If set, all Gokapi URLs for file downloads will include the filename as well. Example: ``https:/gokapi.server/d/1234/File.pdf`` instead of ``https:/gokapi.server/d?id=1234``
- **Public Name** The name that is set in the title. You can for example use your company name
- **Webserver Port** Set the port that Gokapi can be accessed on
- **Public Facing URL** Enter the URL where users from an external network can use to reach Gokapi. The URL will be used for generating download links
- **Redirection URL** By default Gokapi redirects to this URL instead of showing a generic page if no download link was passed
@@ -132,13 +133,13 @@ The following configuration can be set:
Authentication
""""""""""""""
This menu guides you through the authentication setup, where you select how an admin user logs in (only user that can upload files). It is possible to disable authentication completely, but strongly discouraged.
This menu guides you through the authentication setup, where you select how users log in. It is possible to disable authentication completely, but strongly discouraged.
Username / Password
*********************
The default authentication method. A single admin user will be generated that authenticates with a password
The default authentication method. All users authenticate with a username and password. In the next step, you will be asked for the credentials for an admin account.
OAuth2 OpenID Connect
@@ -147,49 +148,44 @@ OAuth2 OpenID Connect
Setup interface
========================
Use this to authenticate with an OIDC server, e.g. Google or an internal server like Authelia or Keycloak.
Use this to authenticate with an OIDC server, e.g. Google or an internal server like Authelia or Keycloak. It is required that users have an email associated with their OIDC account.
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Option | Expected Entry | Example |
+=====================+===================================================================================================+=========================================+
| Provider URL | The URL to connect to the OIDC server | https://accounts.google.com |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Client ID | Client ID provided by the OIDC server | [random String] |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Client Secret | Client secret provided by the OIDC server | [random String] |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Admin email | The email address used to identify the super-admin | gokapi@company.com |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Recheck identity | How often to recheck identity. | 12 hours |
| | | |
| | If the OIDC server is configured to remember the consent, the user should not receive any further | |
| | | |
| | login prompts and it can be ensured, that the user still exist on the server. | |
| | | |
| | Otherwise the user has actively grant access every time the identity is rechecked. In that case | |
| | | |
| | a higher interval would make sense. | |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Restrict to groups | Only allow users that are part of authorised groups to access Gokapi | true |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Scope for groups | The OIDC scope that contains the group info | groups |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Only existing users | When selected, a new user will not be created automatically | checked |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Authorised groups | List of groups that are authorised to log their users in as an admin, separated by semicolon. | admin;dev;gokapi-\* |
| | | |
| | ``*`` can be used as a wildcard | |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Option | Expected Entry | Example |
+====================+===================================================================================================+=========================================+
| Provider URL | The URL to connect to the OIDC server | https://accounts.google.com |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Client ID | Client ID provided by the OIDC server | [random String] |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Client Secret | Client secret provided by the OIDC server | [random String] |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Recheck identity | How often to recheck identity. | 12 hours |
| | | |
| | If the OIDC server is configured to remember the consent, the user should not receive any further | |
| | | |
| | login prompts and it can be ensured, that the user still exist on the server. | |
| | | |
| | Otherwise the user has actively grant access every time the identity is rechecked. In that case | |
| | | |
| | a higher interval would make sense. | |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Restrict to users | Only allow authorised users to access Gokapi that are listed below | true |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Scope for users | The OIDC scope that contains the user info | email |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Authorised users | List of users that are authorised to log in as an admin, separated by semicolon. | \*\@company.com;admin\@othercompany.com |
| | | |
| | ``*`` can be used as a wildcard | |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Restrict to groups | Only allow users that are part of authorised groups to access Gokapi | true |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Scope for groups | The OIDC scope that contains the group info | groups |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| Authorised groups | List of groups that are authorised to log their users in as an admin, separated by semicolon. | admin;dev;gokapi-\* |
| | | |
| | ``*`` can be used as a wildcard | |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
.. note::
If login is restricted to users and groups, both need to be present for a user to access. That means if a user has only one of the two factors, access to the admin menu will be denied.
.. note::
A user will be authenticated until the time specified in ``Recheck identity`` has passed. To log out all users immediately, re-run the setup with `--reconfigure`` and complete it. Thereafter all active session will be deleted.
If a user was disabled in OIDC, the they will still be able to login to Gokapi until the time specified in ``Recheck identity`` has passed. To prevent the user from
logging in immediately, the respective Gokapi user account should be deleted through the UI.
.. note::
@@ -217,7 +213,7 @@ Header Authentication
Only use this if you are running Gokapi behind a reverse proxy that is capable of authenticating users, e.g. by using Authelia or Authentik. Keycloak does apparently not support this feature.
Enter the key of the header that returns the username. For Authelia this would be ``Remote-User`` and for Authentik ``X-authentik-username``.
Separate users with a semicolon or leave blank to allow any authenticated user, e.g. ``gokapiuser@gmail.com;companyadmin@gmail.com``
Enter the username for the admin in the respective field. If ``Only allow already existing users to log in``, new users will not be able to use Gokapi until an account was created through the UI.
Disabled / Access Restriction
@@ -245,7 +241,7 @@ This option disables Gokapis internal authentication completely, except for API
Storage
""""""""""""""
Here you can choose where uploaded files shall be stored. Use the option to always store image files to the local storage, if you want to use encryption for cloudstorage, but require hotlink support.
Here you can choose where uploaded files shall be stored. If you select cloud storage, you have the option to always store image files to the local storage. That way you can use encryption for cloudstorage, but also have hotlink support.
If using cloud storage, by default Gokapi creates a pre-signed download link for files to be downloaded (basically a URL that can only be used for a very short time). If your storage is not accessible from the internet or if you prefer to not expose any cloud storage URLs, you can choose to proxy the downloads. That way Gokapi downloads them and passes them to the user through the Gokapi service.

3
docs/static/custom.css vendored Normal file
View File

@@ -0,0 +1,3 @@
.wy-nav-content {
max-width: 80% !important;
}