|
2 years ago | |
---|---|---|
.. | ||
README.md | 2 years ago |
README.md
How to self-host KeeWeb
Introduction to KeeWeb
KeeWeb (official website) is a web-based implementation of KeePass (official website), an open source and offline password manager.
KeeWeb is available via web browsers on all platforms including mobile, and also featured as an Electron (official website) app on Windows, Linux and Mac operating systems.
Introduction to self-hosting
Self-hosting consists in hosting a service on the user's own server.
Well-known examples of self-hostable services are WordPress for blog editing and Nextcloud for file sharing.
However, the case of KeeWeb is specific because it has no server-side : it only consists in a progressive web app (Wikipedia) with front-end features.
Therefore, the only purpose of self-hosting KeeWeb is self-hosting your password database file (.kdbx
), thus saving you time not having to import it from your device/cloud.
Introduction to WebDAV
WebDAV (Wikipedia) is a file transfer feature implemented within the HTTP protocol, allowing web applications like KeeWeb to upload a file from the client to the server without requiring any back-end.
Requirements
For this tutorial, we'll be using an Apache (official website) web server on Debian (official website) operating system, assuming that you know the basics of them.
KeeWeb also requires a valid HTTPS certificate, therefore, you also need a domain name and eventually a subdomain, assuming that you know the basics of managing domains.
Step 1/3 — Download & extract KeeWeb
KeeWeb's release files are available at the project's repository (GitHub), we're more specifically looking for the latest .html.zip
file, which only contains the web files.
Method 1 : server-side
NOTE : pay attention to version number if you copy/paste the commands.
-
Download the archive into the server
wget https://github.com/keeweb/keeweb/releases/download/v1.14.0/KeeWeb-1.14.0.html.zip
-
Extract the archive
unzip KeeWeb-1.14.0.html.zip
(NOTE : files will be extracted in the current folder)
Method 2 : client-side
- Download the archive into your computer
- Extract the archive
- Upload the extracted files to your server
Step 2/3 — Import your KDBX file(s)
Upload
In your KeeWeb installation directory :
- Create a folder which will contain your KDBX file(s)
mkdir kdbx
- Upload your KDBX file(s) into it
Configure
In your KeeWeb installation directory :
- Edit the
index.html
file - Find
<meta name="kw-config" content="(no-config)">
- Replace by
<meta name="kw-config" content="./config.json">
- Create a
config.json
file
JSON, aka. JavaScript Object Notation (Wikipedia) is standardized data format, which, in this case, allows us to define KeeWeb's configuration.
The KeeWeb configuration is divided in two parts called settings
(allowing to define the app's default behavior) and files
(allowing to specify the default KDBX files to import).
Here's an example :
{
"settings": {
"theme": "te",
"locale": "en",
"canOpen": false,
"canOpenDemo": false,
"canOpenSettings": false,
"canCreate": false,
"canImportXml": false,
"dropbox": false,
"webdav": false,
"gdrive": false,
"onedrive": false
},
"files": [
{
"storage": "webdav",
"name": "Example file #1",
"path": "./kdbx/example.kdbx"
},
{
"storage": "webdav",
"name": "Example file #2",
"path": "./kdbx/example2.kdbx"
}
]
}
The theme
key accepts the following values to specify a theme :
fb
for Flat bluedb
for Dark brownsd
for Solarized darksl
for Solarized lightwh
for Whitete
for Terminalhc
for High contrast
The locale
key accepts the following values to specify a theme :
en
for Englishde-DE
for Germanfr-Fr
for French
The rest defines whether the user can open files from external sources. In our use case, these features are useless, so they're all disabled.
The files
key is a list of files that can be opened out of the box, that's what we're interested in.
A file item has :
- a
storage
key, which value will always bewebdav
for our use case - a
name
key, which value will be displayed in your app's home page - a
path
key, which value points to the KDBX file in your server
Step 3/3 — Setup Apache
Create a virtual host configuration
As you should know, Apache virtual hosts configuration files are located at /etc/apache2/sites-available
.
If you want to create a domain or subdomain for your KeeWeb installation :
- Create a
.conf
file
If you want to use an existing domain or subdomain for your KeeWeb installation :
- Edit your existing configuration file
Setup a domain or subdomain
If you already have a ready-to-use domain or subdomain with HTTP and HTTPS working, you can skip this step.
-
Create a virtual host For HTTP :
<VirtualHost *:80> ServerName kw.example.com RewriteEngine On RewriteCond %{HTTPS} off RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} </VirtualHost>
For HTTPS :
<VirtualHost *:443> ServerName kw.example.com DocumentRoot /your/keeweb/path SSLCertificateFile /your/public/key/path SSLCertificateKeyFile /your/private/key/path </VirtualHost>
-
Replace
ServerName
(for HTTP and HTTPS) with your domain/subdomain
(documentation) -
Replace
DocumentRoot
(for HTTP and HTTPS) with your KeeWeb install path
(documentation) -
Replace
SSLCertificateFile
with your SSL public key path
(documentation) -
Replace
SSLCertificateKeyFile
with your SSL private key path
(documentation)
If you're setting up a new domain or subdomain, you must create, in your domain provider's DNS zone, a new entry, of type A
, with your server's IP address as value.
Setup WebDAV
WebDAV is disabled my default. Therefore, you need to enable it in your configuration file for the directory containing your KDBX file(s) by specifying its absolute path.
-
Specify the path according to your file system (recommended)
<Directory "/var/www/kw.example.com/kdbx"> DAV On Options Indexes </Directory>
or
-
Specify the path according to your web structure
<Location "/kdbx"> DAV On Options Indexes </Location>
Enable modules
SSL and WebDAV are modules and must be enabled prior to applying the configuration, using the a2enmod
("Apache 2 enable module") command.
If you configured SSL for the first time :
a2enmod ssl
If you configured WebDAV for the first time :
a2enmod dav
a2enmod dav_fs
Enable virtual host
As you should know, a newly created virtual host configuration must be enabled using the a2ensite
("Apache 2 enable website") command, and specifiying your configuration file's name as only parameter.
a2ensite keeweb.conf
This command will create a symbolic link (Wikipedia) from /etc/apache2/sites-available
to /etc/apache2/sites-enabled
.
Restart Apache
As you should know, the Apache service must be restarted after changing its configuration, in order to apply it.
systemctl restart apache2
Troubleshooting
Apache fails to restart
You'll find detailed Apache errors :
- using the
systemctl status apache2
command - using the
journalctl -xe
command (documentation) - in the
/var/log/apache2/error.log
file
KeeWeb can't open
Make sure that file paths are correct :
- in your Apache
.conf
file located at/etc/apache2/sites-available
- in your KeeWeb
config.json
file located at your installation path
Make sure that Apache's user has read permissions on the KDBX folder, see below.
KeeWeb can't sync
Make sure that Apache's user has read and write permissions on the KDBX folder.
The recommanded way : your user is owner of all files by default, it can stay that way, but Apache's user can be set as group user, to be given appropriate permissions.
From your KeeWeb installation directory :
- Set Apache's user as group
chgrp -R www-data kdbx
(documentation) - Allow group user to read and write
chmod -R g+rw kdbx
(documentation)
NOTE : I experienced issues specifically on Firefox browser which may not be resolvable for now. Please try Chromium (maintainer website) or Chromium-based browsers.
Reset KeeWeb
After changing KeeWeb's configuration, you may need to clear the app's data (local storage) from your web browser.