Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 19, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3227013
Removed old static and template folder implementation, added serving …
Forceu Apr 3, 2025
9a605bb
Merge branch 'master' into customcss
Forceu Apr 19, 2025
57be202
Merge branch 'master' into customcss
Forceu Apr 24, 2025
86c0be1
Merge branch 'master' into customcss
Forceu May 3, 2025
68f756a
Implement custom JS/CSS inclusion
Forceu May 3, 2025
51181d3
Update documentation
Forceu May 16, 2025
d79ac06
Updated docs
Forceu May 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,4 @@ internal/webserver/web/e2e.wasm
internal/webserver/web/static/js/wasm_exec.js
internal/webserver/web/static/js/min/wasm_exec.min.js
.vendor/
custom/
14 changes: 8 additions & 6 deletions docs/advanced.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
6 changes: 4 additions & 2 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -53,7 +53,9 @@
# 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
Expand Down
199 changes: 94 additions & 105 deletions docs/examples.rst
View file
Open in desktop

Large diffs are not rendered by default.

84 changes: 40 additions & 44 deletions docs/setup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.

+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| 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 | |
+--------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
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 | [email protected] |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+
| 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 | |
+---------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------+

.. 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::
Expand Down Expand Up @@ -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. ``[email protected];[email protected]``
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
Expand Down Expand Up @@ -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.

Expand Down
3 changes: 3 additions & 0 deletions docs/static/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.wy-nav-content {
max-width: 80% !important;
}
2 changes: 1 addition & 1 deletion internal/configuration/setup/templates/setup.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,7 +280,7 @@
<div class="wizard-input-section">
<div class="form-group">
<p>
Please enter the OIDC client configuration. Multiple users and groups can be separated with a semicolon. The <a href="https://gokapi.readthedocs.io/en/stable/setup.html#oauth2-openid-connect" target="_blank" rel="noopener noreferrer">documentation</a> has examples on how to configure for different providers.<br>
Please enter the OIDC client configuration. Groups can be separated with a semicolon. The <a href="https://gokapi.readthedocs.io/en/stable/setup.html#oauth2-openid-connect" target="_blank" rel="noopener noreferrer">documentation</a> has examples on how to configure for different providers.<br>
</p>

<div class="col-sm-8" style="width:90%">
Expand Down
Loading