Andreas/wekan
1
0
Fork 0
mirror of https://github.com/wekan/wekan.git synced 2025-12-23 10:50:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Reorganized Docs. In Progress.

Browse source
This commit is contained in:
Lauri Ojansivu 2024-06-27 11:08:43 +03:00
parent 1961e22cbd
commit ce89ff4833
202 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

143
docs/Webserver/Apache.md Normal file
View file

@ -0,0 +1,143 @@
## 1) Enable Mod_Proxy
```
sudo a2enmod ssl proxy proxy_http proxy_wstunnel proxy_balancer
```
[Apache Mod_Proxy documentation](http://httpd.apache.org/docs/current/mod/mod_proxy.html)
## 2) Restart Apache
Systemd:
```
sudo systemctl restart apache2
```
Init.d:
```
sudo service apache2 restart
```
## 3) Enable SSL in Apache config
```
Listen 443
NameVirtualHost *:443
```
## 4) Set Apache proxy
Remember to set `- ROOT_URL=` to the full URL used for your reverse proxy or as `ServerName`.
### a) Main URL
SSL with [Certbot](https://certbot.eff.org).
Config at `/etc/apache2/sites-available/example.com.conf`:
```ApacheConf
<VirtualHost *:443>
ServerName example.com
SSLEngine On
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
ServerSignature Off
<Location />
require all granted
</Location>
ProxyPassMatch "^/(sockjs\/.*\/websocket)$" "ws://127.0.0.1:3001/$1"
ProxyPass "/" "http://127.0.0.1:3001/"
ProxyPassReverse "/" "http://127.0.0.1:3001/"
<Proxy *>
Options FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all
</Proxy>
</VirtualHost>
```
### b) Sub URL
Currently, favicon loading does not work with sub-url [wekan/issues/1692](https://github.com/wekan/wekan/issues/1692)
Config at `/etc/apache2/sites-available/example.com.conf`:
```ApacheConf
<VirtualHost *:443>
ServerName example.com/wekan
SSLEngine On
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
ServerSignature Off
ProxyPassMatch "^/(sockjs\/.*\/websocket)$" "ws://127.0.0.1:3001/wekan/$1"
ProxyPass "/wekan" "http://127.0.0.1:3001/wekan"
ProxyPassReverse "/wekan" "http://127.0.0.1:3001/wekan"
<Proxy *>
Options FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all
</Proxy>
</VirtualHost>
```
To run as default site:
```ApacheConf
<VirtualHost _default_:443>
```
## 5) Enable your site
```
sudo a2ensite example.com
```
Or, add symlink manually:
```
sudo su
cd /etc/apache2/sites-enabled
ln -s ../sites-available/example.com.conf example.com.conf
```
On some distributions, Apache config is at different path:
```
cd /etc/httpd/conf.d
```
## 6) Reload Apache
Systemd:
```
sudo systemctl restart apache2
```
Init.d:
```
sudo service apache2 restart
```
## 7) Snap settings
### a) Main URL
```
sudo snap set wekan port='3001'
sudo snap set wekan root-url='https://example.com'
```
### b) Sub URL
```
snap set wekan port='3001'
snap set wekan root-url='https://example.com/wekan'
```
[All snap settings](https://github.com/wekan/wekan-snap/wiki/Supported-settings-keys)

281
docs/Webserver/Caddy-Webserver-Config.md Normal file
View file

@ -0,0 +1,281 @@
[Caddy 2 .well-known/assetlinks.json config for WeKan Android Play Store app](../PWA#fullscreen-android-app-with-caddy-and-wekan-server)
## Caddy 2
WeKan Snap Candidate for any Snap distros: https://github.com/wekan/wekan/wiki/OpenSuse , disable internal old Caddy 1, when using Caddy 2:
```
sudo snap set wekan caddy-enabled='false'
sudo snap set wekan port='3001'
sudo snap set wekan root-url='https://boards.example.com'
```
More info about root-url at https://github.com/wekan/wekan/wiki/Settings
Browser needs to have only one language https://github.com/wekan/wekan/issues/4803#issuecomment-1374354425
Install Caddy 2 stable release: https://caddyserver.com/docs/install#debian-ubuntu-raspbian
Like this:
```
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt -y install caddy
```
Edit Caddyfile:
```
sudo nano /etc/caddy/Caddyfile
```
Example:
```
# Redirecting http to https
(redirect) {
@http {
protocol http
}
redir @http https://{host}{uri}
}
# WeKan board, proxy to localhost port, or IP-ADDRESS:PORT
boards.example.com {
tls {
load /var/snap/wekan/common/certs
alpn http/1.1
}
reverse_proxy 127.0.0.1:3025
}
# Static website
example.com {
tls {
load /var/snap/wekan/common/certs
alpn http/1.1
}
root * /var/websites/wekan.team
file_server
}
# Files download directory browse website
files.example.com {
root * /var/websites/ftp.secretchronicles.org/public
file_server browse
}
```
Caddy commands list:
```
caddy help
```
***
[Caddy OAuth2 with Let's Encrypt SSL example](OAuth2)
***
## CloudFlare free wildcard SSL *start*
Also works with other SSL certs.
### 1) Requirements: You have changed nameservers to CloudFlare.
### 2) Get CloudFlare SSL wildcard Origin Certificate
Go to CloudFlare login/example.com/Crypto/Origin Certificates.
Create and download certs for `*.example.com, example.com`
### 3) Create directory /var/snap/wekan/common/certs
```
sudo su
cd /var/snap/wekan/common
mkdir certs
cd certs
```
### 4) Create cert file
Create file: `example.com.pem` with content of CloudFlare Origin Certificates.
```
nano example.com.pem
```
There add certs:
```
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
```
Then Save: Ctrl-o Enter
Then Exit: Ctrl-x.
### 5) Set permissions rw-r--r-- to example.com.pem:
```
chmod 644 example.com.pem
```
### 6) Edit Caddy webserver config
```
sudo nano /var/snap/wekan/common/Caddyfile
```
There change config:
```
http://example.com https://example.com {
tls {
load /var/snap/wekan/common/certs
alpn http/1.1
}
proxy / localhost:3001 {
websocket
transparent
}
}
```
Save: Ctrl-o Enter
Exit: Ctrl-x
Enable Caddy:
```
sudo snap set wekan caddy-enabled='true'
sudo snap set wekan port='3001'
sudo snap set wekan root-url='https://example.com'
```
### 7) Enable CloudFlare SSL
Click CloudFlare login/example.com/DNS.
Check that status of your domains have orange cloud color, so traffic goes through CloudFlare SSL.
Click CloudFlare login/example.com/Page Rules.
Set for example:
```
1) http://example.com/*
Always Use HTTPS
2) http://*.example.com/*
Always use HTTPS
```
Optionally, if you want caching:
```
3) *example.com/*
Cache Level: Cache Everything
```
## CloudFlare free wildcard SSL *end*
***
## Other config stuff
[List of Let's Encrypt implementations](https://community.letsencrypt.org/t/list-of-client-implementations/2103)
## Caddy webserver config with logs
Create directory for caddy, website and logs:
```bash
mkdir -p ~/caddy/example.com ~/caddy/logs
```
Add this config to ~/caddy/Caddyfile
There's also some extra examples.
```bash
example.com {
root /home/username/caddy/example.com
# Static website, markdown or html
ext .md .html
proxy /wekan 127.0.0.1:3000 {
websocket
}
log /home/username/caddy/logs/wekan-access.log {
rotate {
size 100 # Rotate after 100 MB
age 7 # Keep log files for 7 days
keep 52 # Keep at most 52 log files
}
}
errors {
log /home/username/caddy/logs/wekan-error.log {
size 100 # Rotate after 100 MB
age 7 # Keep log files for 7 days
keep 52 # Keep at most 52 log files
}
}
}
example.com/files {
root /home/username/files
# View files in directory, has sorting in browser
browse
}
```
Install Caddy. Change username to what user you run caddy, like in /home/username , and Let's Encrypt email to your email adderess:
```bash
# Install caddy with some plugins
curl https://getcaddy.com | bash -s personal http.ipfilter,http.mailout,http.ratelimit,http.realip
```
# Give permissions to caddy to bind 80 and 443
```
sudo setcap cap_net_bind_service=+ep /usr/local/bin/caddy
```
And this service file for Caddy to /etc/systemd/system/caddy@.service
```bash
; see `man systemd.unit` for configuration details
; the man section also explains *specifiers* `%x`
[Unit]
Description=Caddy HTTP/2 web server %I
Documentation=https://caddyserver.com/docs
After=network-online.target
Wants=network-online.target
Wants=systemd-networkd-wait-online.service
[Service]
; run user and group for caddy
User=username
Group=username
ExecStart=/home/username/caddy/caddy -conf=/home/username/caddy/Caddyfile -agree -email="admin@example.com"
Restart=on-failure
StartLimitInterval=86400
StartLimitBurst=5
RestartSec=10
ExecReload=/bin/kill -USR1 $MAINPID
; limit the number of file descriptors, see `man systemd.exec` for more limit settings
LimitNOFILE=1048576
LimitNPROC=64
; create a private temp folder that is not shared with other processes
PrivateTmp=true
PrivateDevices=true
ProtectSystem=full
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
```
Start caddy and enable service:
```
sudo systemctl daemon-reload
sudo systemctl start caddy@username
sudo systemctl enable caddy@username
```

121
docs/Webserver/Local-self-signed-TLS.md Normal file
View file

@ -0,0 +1,121 @@
From [ksaadDE](https://github.com/ksaadDE) at https://github.com/wekan/wekan-snap/issues/167
Hi,
I've read that in e.g. https://github.com/wekan/wekan-snap/issues/118 there is assumed that local https wouldn't work (even not for ips). I provide a small guide to fix this.
*Despite the fact that you should **never use self-signed certs in production**. You mess up your TLS Certificate Verification/Validation and therefore exposing yourself to various risks in cyberspace. **For limited local uses it can be valid!***
# General Config
In both cases your `/etc/hosts` should have *a* entry that routes your "domain" `wekan.local` to `127.0.0.1` (=localhost) like this:
```
127.0.0.1 wekan.local
```
You need to enable caddy `sudo snap set wekan caddy-enabled='true'` and set the `root-url` to https://wekan.local.
Keep in mind that 3001 is the wekan webapp port, not the caddy port(!). Caddy will use 80 and 443.
# Option 1: `tls self_signed` 7d Dev Certificate (Caddy<v2)
Your `/var/snap/wekan/common/Caddyfile` should look like this:
```
https://wekan.local {
tls self_signed
proxy / localhost:3001 {
websocket
transparent
}
}
```
Restart your Wekan snap service: `sudo snap restart wekan && sudo snap restart wekan.caddy` voila!
*Drawback:* There is a significant drawback in doing so, because the public docs of caddy stating that below caddyV2 (like in our snap) there's only a seven day life span given. Due to the origin intent of testing, not for production.
# Option 2: Custom, long-living, self-signed TLS Cert
Your `/var/snap/wekan/common/Caddyfile` should look like this:
```
https://wekan.local {
tls /var/snap/wekan/common/certs/certificate.pem /var/snap/wekan/common/certs/key.pem
proxy / localhost:3001 {
websocket
transparent
}
}
```
Create a bash script using `sudo nano /var/snap/wekan/common/certs/certgen.sh` :
```
#!/bin/bash
# this script checks existence of CERTFILE and KEYFILE in current directory and moves existing files to FILE.old then generating new TLS certs (self-signed) with a CN of $SERVERNAME, finally it restarts the snap wekan service + caddy
ROOTPATH="/var/snap/wekan/common/certs"
SERVERNAME="wekan.local"
CERTFILE="$ROOTPATH/certificate.pem"
KEYFILE="$ROOTPATH/key.pem"
if [ -f "$CERTFILE" ]; then
echo "[+] backing up '$CERTNAME'";
sudo mv "$CERTFILE" "$CERTNAME.old";
fi
if [ -f "$KEYFILE" ]; then
echo "[+] backing up '$KEYFILE'";
sudo mv "$KEYFILE" "$KEYFILE.old";
fi
echo "[+] Trying to generate certs";
sudo openssl req -newkey rsa:4096 \
-x509 \
-sha256 \
-days 3650 \
-nodes \
-out "$CERTFILE" \
-keyout "$KEYFILE" \
-subj "/C=SI/ST=Ljubljana/L=Ljubljana/O=Security/OU=IT Department/CN=$SERVERNAME" &>/dev/null
if [ ! -f "$CERTFILE" ]; then
echo "[-] can't fiund '$CERTFILE' seemingly the generation failed";
exit
fi
if [ ! -f "$KEYFILE" ]; then
echo "[-] can't find '$KEYFILE' seemingly the generation failed";
exit
fi
echo "[+] completed TLS-Cert generation";
# restart snap wekan && wekan.caddy
echo "[+] restarting snap wekan service";
sudo snap restart wekan &>/dev/null
sudo snap restart wekan.caddy &>/dev/null
echo "[+] completed restart snap wekan service";
echo " ";
echo "[i] please check https://$SERVERNAME/"
```
This file generates two files `certificate.pem` and `key.pem`, then checks their existence in `/var/snap/wekan/common/certs/` (same dir). If the CERTFILE or KEYFILE already existing, it will move the existing files to <fname>.old. Then it restarts the wekan services wekan and caddy. Afterwards it shows you the address to visit.
Make the sh file executable `sudo chmod u+x ./runfiles.sh`
Finally, run `sudo ./runfiles.sh` and it should work at the address being recommended to visit.
### Things to keep note of
- Don't try to use `load` it won't work!
- Don't mess around without a SERVERNAME... it won't work
- Don't use the default caddy file with this tls subdirectives. It won't work and break into No Connection or `PR_END_OF_FILE_ERROR` (firefox)
- Caddy has bugs with self_signed certificates for Caddy < 2 (below caddyv2)
- **FIREWALL CONFIG:** Don't forget to block in and out 3001 for outside connections (e.g. using ufw or nfttables / iptables)
### Sources:
- https://linuxize.com/post/creating-a-self-signed-ssl-certificate/ (openssl cmd)
- https://caddy.community/t/proper-way-to-utilize-self-signed-certificates/7264 (reading docs and issues of caddy)
- https://caddy.community/t/tls-self-signed-not-working/5057
- - https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config (Wekan Docs)
- https://github.com/wekan/wekan-snap/issues/118
- Snap Wekan Docs
Greetings from Germany <3

253
docs/Webserver/Nginx-Webserver-Config.md Normal file
View file

@ -0,0 +1,253 @@
## If you get 'Welcome to Nginx' screen after setting up config
From https://github.com/wekan/wekan/issues/3190
I installed Nginx using the instructions on the [AWS wiki](AWS)
I followed the [the Nginx wiki](Nginx-Webserver-Config) and reached a point where everything was installed correctly and 'sudo nginx -t' was passing (with warnings), but when I went to the root-url I was still getting the generic welcome screen from nginx saying 'Welcome to nginx! If you see this page, the nginx web server is successfully installed and working. Further configuration is required'
I got stuck here for a very long time, fiddling with my config files, until I found [this answer](https://stackoverflow.com/questions/11426087/nginx-error-conflicting-server-name-ignored). In my install, 'default' files had been automatically created in /etc/nginx/conf.d/ and in /etc/nginx/sites-available/
Once I deleted those files, nginx was working instantly. Propose a new step could be added to the wiki, before the 'sudo nginx -t' step, instructing users to check whether they have those 'default' files and delete them if they do.
## CentOS 7
If you use Nginx in front of Wekan on CentOS 7, please try: `setsebool -P httpd_can_network_connect 1`. This should allow nginx or any other webserver to connect to a container. Please [**do not disable SELinux**](https://github.com/wekan/wekan/issues/2792#issuecomment-630222315)
## Nginx requires unsafe-eval for WeKan date format
[Source](https://github.com/wekan/wekan/issues/4220#issuecomment-990243775)
Thank you for your answers. I figured out that in my nginx config I needed to add allow `unsafe-eval`:
Old:
```
add_header Content-Security-Policy "default-src 'self' 'unsafe-inline'";
```
Now:
```
add_header Content-Security-Policy "default-src 'self' 'unsafe-inline' 'unsafe-eval'";
```
This solves my problem.
Thanks
## Attachment file size
[Source](https://github.com/wekan/wekan/issues/2103#issuecomment-455014303)
`/etc/nginx.conf`:
```
http {
...
client_max_body_size 100M;
}
```
## Others
[Meteor.js on Ubuntu 14.04 with nginx](https://www.digitalocean.com/community/tutorials/how-to-deploy-a-meteor-js-application-on-ubuntu-14-04-with-nginx)
[List of Let's Encrypt implementations](https://community.letsencrypt.org/t/list-of-client-implementations/2103)
[Certbot: Let's Encrypt SSL for Nginx](https://certbot.eff.org)
Below config is tested with Debian 9, it did receive A+ rating at ssllabs.com test.
## Nginx webserver configs
If you use Wekan at sub url, change / to /wekan .
### /etc/nginx/conf.d/example.com.conf or /etc/nginx/sites-available/example.com.conf:
```
# this section is needed to proxy web-socket connections
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# HTTP
server {
listen 80; # if this is not a default server, remove "default_server"
listen [::]:80 ipv6only=on;
server_name example.com;
# redirect non-SSL to SSL
location / {
rewrite ^ https://example.com$request_uri? permanent;
}
}
# HTTPS server
server {
listen 443 ssl http2; # we enable HTTP/2 here (previously SPDY)
server_name example.com; # this domain must match Common Name (CN) in the SSL certificate
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# If your application is not compatible with IE <= 10, this will redirect visitors to a page advising a browser update
# This works because IE 11 does not present itself as MSIE anymore
if ($http_user_agent ~ "MSIE" ) {
return 303 https://browser-update.org/update.html;
}
# Pass requests to Wekan.
# If you have Wekan at https://example.com/wekan , change location to:
# location /wekan {
location / {
# proxy_pass http://127.0.0.1:3001/wekan;
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade; # allow websockets
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-For $remote_addr; # preserve client IP
# this setting allows the browser to cache the application in a way compatible with Meteor
# on every applicaiton update the name of CSS and JS file is different, so they can be cache infinitely (here: 30 days)
# the root path (/) MUST NOT be cached
#if ($uri != '/wekan') {
# expires 30d;
#}
}
}
```
### /etc/nginx/nginx.conf
```
user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;
events {
worker_connections 768;
# multi_accept on;
}
http {
##
# Basic Settings
##
## Max attachment size that can be uploaded to Wekan:
client_max_body_size 100M;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
types_hash_max_size 2048;
server_tokens off;
set_real_ip_from 0.0.0.0/32; # All addresses get a real IP.
real_ip_header X-Forwarded-For;
limit_conn_zone $binary_remote_addr zone=arbeit:10m;
client_body_timeout 60;
client_header_timeout 60;
keepalive_timeout 10 10;
send_timeout 60;
reset_timedout_connection on;
# server_names_hash_bucket_size 64;
# server_name_in_redirect off;
include /etc/nginx/mime.types;
default_type application/octet-stream;
##
# SSL Settings
##
ssl_protocols TLSv1.2 TLSv1.1 TLSv1; # Dropping SSLv3, ref: POODLE
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:30m;
ssl_session_timeout 1d;
ssl_ciphers ECDH+aRSA+AESGCM:ECDH+aRSA+SHA384:ECDH+aRSA+SHA256:ECDH:EDH+CAMELLIA:EDH+aRSA:+CAMELLIA256:+AES256:+CAMELLIA128:+AES128:+SSLv3:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS:!RC4:!SEED:!ECDSA:CAMELLIA256-SHA:AES256-SHA:CAMELLIA128-SHA:AES128-SHA;
ssl_dhparam /etc/ssl/dh_param.pem;
ssl_ecdh_curve secp384r1;
ssl_stapling on;
ssl_stapling_verify on;
add_header X-XSS-Protection '1; mode=block';
add_header X-Frame-Options SAMEORIGIN;
add_header Strict-Transport-Security 'max-age=31536000';
add_header X-Content-Options nosniff;
add_header X-Micro-Cache $upstream_cache_status;
##
# Logging Settings
##
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;
##
# Gzip Settings
##
gzip on;
gzip_disable "msie6";
gzip_buffers 16 8k;
gzip_comp_level 1;
gzip_http_version 1.1;
gzip_min_length 10;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/x-icon application/vnd.ms-fontobject font/opentype application/x-font-ttf;
gzip_vary on;
gzip_proxied any; # Compression for all requests.
##
# Virtual Host Configs
##
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
}
```
# Installing
If you have example.com.conf at /etc/nginx/sites-available/example.com.conf, make symlink to sites-available:
Nginx
```
sudo apt install nginx
sudo systemctl start nginx
sudo systemctl enable nginx # service
```
Nginx configs
```
sudo su
cd /etc/nginx/sites-enabled
ln -s ../sites-available/example.com.conf example.com.conf
```
:heavy_exclamation_mark: Check if the user "www-data" exist on your system, if no, you can set "nginx" user in /etc/nginx/nginx.conf
Test nginx config for errors:
```
sudo nginx -t
```
If config is OK, take it into use:
```
sudo systemctl reload nginx (or: sudo service nginx reload)
```
Wekan Snap
```
sudo apt install snapd
sudo snap install wekan
sudo snap set wekan root-url="https://example.com/wekan"
sudo snap set wekan port="3001"
sudo systemctl restart snap.wekan.mongodb
sudo systemctl restart snap.wekan.wekan
```
More info about backups etc at https://github.com/wekan/wekan-snap/wiki

81
docs/Webserver/Scaling.md Normal file
View file

@ -0,0 +1,81 @@
https://galaxy-guide.meteor.com/scaling
***
Reply from customer at 2023-09-29 about WeKan v7.08:
> The good thing is that that new version is working really well and being able to spread the load between 4 OpenShift pods changes everything.
Maybe related to these improvements:
- https://github.com/wekan/wekan/pull/5136
- https://github.com/wekan/wekan/issues/5000
[Optimizing Nested Imports](https://zodern.me/posts/nested-imports/)
## Scaling [Wekan Snap with Automatic Updates](https://github.com/wekan/wekan-snap/wiki/Install)
Recommended specs:
- Try to add [Redis Oplog](https://github.com/cult-of-coders/redis-oplog) like [this](Emoji#how-you-could-add-another-plugin)
- One bare metal server (or VM on server that does not have oversubscription), for example [Fastest: UpCloud](https://upcloud.com), [Hetzner](https://www.hetzner.com/?country=en), [Packet](https://packet.com).
- NVME or SSD disk. Speed difference when opening Wekan board: SSD 2 seconds, HDD 5 minutes.
- Minimum 60 GB total disk space, 40 GB free disk space, [Daily Backups](Backup) to elsewhere, monitoring and alerting if server has low disk space, because disk full causes database corruption.
- Newest Ubuntu 64bit
- 4GB RAM minimum. See with `free -h` is server is using any swap. If it is, add more RAM.
- some performance optimized CPUs/cores. 2 minimum, 4 is better. See with `nproc` how many CPUs you have. Look with `top` or `htop` is server using max 100% CPUs, if it is, add higher performance optimized CPUs (or more CPUs). But if it looks like Wekan not using some of those added CPUs, then adding more CPUs is not useful.
- Do not store attachments at database, like uploading file to card. Have markdown links to files, like `[Document](https://example.com/files/document.doc)`. Click `Wekan board` => `☰` => `⚙` => `Board Settings` => `Card Settings`. There uncheck `[_] Attachments` to hide attachments at card.
- Click Wekan `Admin Panel / Settings / Accounts / Hide System Messages of All Users`. If someone needs to show system messages, they can click slider at opened card to show them. Sometime later, if many have manually enabled showing system messages, click that same button at Admin Panel again.
- Check Webhooks: Do you have `Admin Panel / Settings / Global Webhooks` (that sends most board actions to webhook) or at each board, per-board webhooks (that sends most one board actions to webhook, more info at [wiki right menu Webhooks](https://github.com/wekan/wekan/wiki)) at `Wekan board` => `☰` => `⚙` => `Outgoing Webhooks`. You also see this with [DBGate](Backup#dbgate-open-source-mongodb-gui) at port localhost:27019 / database: wekan / table: integrations. Each webhook should [immediately return 200 response before processing any data](https://github.com/wekan/wekan/issues/3575), because otherwise it will slow down Wekan a lot.
- In future Wekan version will be added as default:
- [Setting `NODE_OPTIONS: --max_old_space_size=4096`](https://github.com/wekan/wekan/issues/3585#issuecomment-782431177)
Minimum specs:
- [RasPi3](Raspberry-Pi), 1 GB RAM, external SSD disk for Wekan and MongoDB.
- While it works, it's only for minimal usage.
- Newer RasPi recommended for minimum use.
## Alternatives
At https://wekan.github.io / Download / Kubernetes or OpenShift, etc
***
# OLD INFO BELOW:
## Story: MongoDB on bare metal
From Tampa:
Hey,
... (about other tries) ...
Last month I threw all this out, recreated all the boards and connected them centrally to a single instance of mongo running on a dedicated server with custom hardware. This was like stepping into the light almost. Since then not a single machine has sent me a mail that it reached 50% usage. It seems insignificant, but the results speak for themselves.
The cloud instances are all shared 1vcpu, 1GB, 10GB storage, they just run wekan natively piped to the background, no docker, no snap, native install. They are connected to the central DB server sitting in the same datacenter. I stuffed a Raid6 with solid disks in that and gave it a hardware controller with a nice big cache. The latency being below 5ms over the network and the DB server having plenty of IO to go around it almost never has a queue of commits going to it and from the cache and IO use I suspect I could grow this tenfold easily.
With this setup each board essentially runs on half the hardware, in terms of cost anyways, yet it works so much better. There seems to be some magic ingredient here, being really fast IO for mongo that reduces system load of wekan by such a large amount that is can practically run even large boards with 40+ concurrent users on the least hardware most cloud providers even offer. With the central server setting up backups has become so much easier, I no longer need to wait for low usage to do backups either.
## Scaling to more users
For any large scale usage, you can:
a) scale with Docker Swarm, etc
b) for big reads or writes, do it on replica
c) for big reads or writes, do it at small amounts at a time, at night, or when database CPU usage seems to be low
Related to docker-compose.yml at https://github.com/wekan/wekan , using Docker Swarm:
[How to scale to more users](https://github.com/wekan/wekan/issues/2711#issuecomment-601163047)
[MongoDB replication docs](https://docs.mongodb.com/manual/replication/)
[MongoDB compatible databases](https://github.com/wekan/wekan/issues/2852)
[AWS](AWS)
[Azure OIDC](Azure)

59
docs/Webserver/Settings.md Normal file
View file

@ -0,0 +1,59 @@
## Standalone Wekan Settings: Snap, Docker, Source etc (not Sandstorm)
## ROOT_URL / root-url
- See https://github.com/wekan/wekan/issues/4803
- Docker/Source/Bundle like this, no quotes, big letters, underscore: `ROOT_URL=http://192.168.0.100`
- **Snap** like this, single quotes, small letters: `sudo snap set wekan root-url='http://192.168.0.100'`
## Webserver config
* [Nginx](Nginx-Webserver-Config)
* [Apache](Apache)
* [Caddy](Caddy-Webserver-Config)
Examples:
1) nginx SSL or without SSL, available at internet:
- root-url='https://example.com' or https://example.com/something or https://something.example.com , or with http
- port='3001'
- [Nginx example, proxying to local port 3001](Nginx-Webserver-Config)
=> Wekan at https://example.com
2) only wekan, no SSL, internal lan, caddy not enabled:
- root-url='http://192.168.1.150'
- port='80'
=> Wekan locally http://192.168.1.150
3) only wekan, no SSL, internal lan, caddy not enabled, wekan at different port:
- root-url='http://192.168.1.150:5000'
- port='5000'
=> Wekan locally http://192.168.1.150:5000
4) wekan's caddy SSL, available at Internet:
- root-url='https://example.com' or https://example.com/something or https://something.example.com
- port='3001'
- [Caddyfile example](https://github.com/wekan/wekan-snap/wiki/Install#7-replace-first-top-line-of-text-with-subdomainexamplecomsuburl-without-any-beginning-of-httphttps)
=> Wekan at https://example.com
Wekan runs http server on local port, so it is without SSL. To get SSL, some webserver like Caddy and Nginx that have SSL, can proxy to local Wekan http port where node.js runs.
## Admin Panel
First registered Wekan user will get [Admin Panel](Features) on new
Docker and source based installs. You can also on MongoDB
[enable Admin Panel](https://github.com/wekan/wekan/blob/main/CHANGELOG.md#v0111-rc2-2017-03-05-wekan-prerelease) and [change you as board admin](https://github.com/wekan/wekan/issues/1060#issuecomment-310545976).
## LAN + VPN
[Using same database for both LAN and VPN Wekan](https://github.com/wekan/wekan-mongodb/blob/master/docker-compose.yml#L86-L100)
## Proxy
[Using Proxy](https://github.com/wekan/wekan/issues/1480)
## Email
[Troubleshooting Mail](Troubleshooting-Mail). For Exchange, you can use [DavMail](http://davmail.sourceforge.net), Wekan SMTP => DavMail => Exchange.
## RAM usage
[RAM usage](https://github.com/wekan/wekan/issues/1088#issuecomment-311843230)

202
docs/Webserver/Traefik-and-self-signed-SSL-certs.md Normal file
View file

@ -0,0 +1,202 @@
Running Wekan Mongodb with Traefik as a reverse proxy with a self-signed cert as containers on a single docker host.
## Background
Craig had been using nginx as a reverse proxy for a restyaboard install, but it was a bit opaque (at least to him) as to how to configure it to reverse proxy for multiple services, so he thought he'd try traefik and use Wekan as the service as a learning exercise and compare the two.
This was done to demo using containers as services (he works in an older style org and they're still stuck in a vmware/vm mentality).
Updated 5-10-18 for wekan v1.52 and mongodb 3.2.21
## Install
Note: my login is a member of the docker group on this docker host so I can exec docker commands.
Created directories:
```
sudo mkdir -p /opt/traefik/certs
sudo chmod 755 /opt/traefik
sudo chmod 750 /opt/traefik/certs
```
Created a self-signed cert and key for the application (its on an internal network so didn't want to mess with the Letsencrypt stuff that requires access to the internet and registered dns domains):
```
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout wekan1.key -out wekan1.crt
```
Copied these to /opt/traefik/certs and set permissions:
```
chmod 644 /opt/traefik/certs/wekan1.crt
chmod 600 /opt/traefik/certs/wekan1.key
```
Create a docker network web to use for traefik - this config doesn't require any ports exposed for wekan-app or wekan-db on the docker-host:
```
docker network create web
```
Created an internal dns entry wekan.myinternaldomain.org that is a cname for the docker host (i.e. Wekan resolves to the ip address of the docker host) - note that this config assumes that ports 80 and 443 don't have any processes from the docker host listening on those ports. If you don't have internal dns - put this in the relevant hosts file on the systems that will access the app, including the docker host.
## Traefik config
added the following to `/opt/traefik/docker-compose.yml`
```
version: '2'
services:
traefik:
image: traefik:latest
ports:
- 80:80
- 443:443
- 8080:8080
networks:
- web
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /opt/traefik/traefik.toml:/traefik.toml
- /opt/traefik/certs/:/certs/
container_name: traefik
networks:
web:
external: true
```
Created `/opt/traefik/traefik.toml` with:
```
debug = false
logLevel = "DEBUG"
defaultEntryPoints = ["https","http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.redirect]
entryPoint = "https"
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
[[entryPoints.https.tls.certificates]]
certFile = "/certs/wekan1.crt"
keyFile = "/certs/wekan1.key"
[entryPoints.eightzero]
address = ":8080"
[api]
entrypoint = "eightzero"
[retry]
[docker]
endpoint = "unix:///var/run/docker.sock"
domain = "docker.localhost"
watch = true
exposedbydefault = false
```
Comments - `docker-compose.yml`:
The image is set as the latest for traefik - you may want to tie it to a particular version. Also added in the entrypoint for the trafik api (8080)
To test:
```
cd /opt/traefik
docker-compose up
```
This will ouput to the terminal till you are ready to run it in the background with `docker-compose up -d` . (stop the container running with Ctrl-c)
It exposes ports 80, 443 and 8080 on the docker host so you can check by webbing to `<docker hostip>` but you should get a 404 error until wekan is up.
```
curl -H Host:wekan.myinternaldomain.org http://localhost
```
mounting `/var/run/docker.sock:/var/run/docker.sock` on the container gives access to docker config so that traefik can be dynamic (thats more advanced) see https://traefik.io/ for extensive docs.
traefik.toml is the config for traefik. It sets up port 80 to redirect to 443. This is a very simple config - there's a whole lot more that you can do.
endpoint under `[docker]` is where changes are read from.
- domain - default dns domain used.
- watch = true - watch docker changes.
- exposedbydefault = false - If set to false, containers that don't have `traefik.enable=true` will be ignored. (I haven't tried it with other containers yet so I've set it to false).
Now for Wekan:
This fairly standard with the addition of some labels(handy notes have been removed for brevity)
```
version: '2'
services:
wekandb:
image: mongo:3.2.21
container_name: wekan-db
restart: always
command: mongod --smallfiles --oplogSize 128
networks:
- web
expose:
- 27017
volumes:
- wekan-db:/data/db
- wekan-db-dump:/dump
wekan:
image: quay.io/wekan/wekan:v1.52
container_name: wekan-app
restart: always
networks:
- web
# traefik magic stuff here
labels:
- "traefik.backend=wekan-app"
- "traefik.docker.network=web"
- "traefik.frontend.rule=Host:wekan.myinternaldomain.org"
- "traefik.enable=true"
- "traefik.port=8080"
- "traefik.default.protocol=http"
#note: mail url points to ip address of docker host which has postfix running as a relay
# for docker apps. ping me at email: silvacraig@gmail.com if you want the postfix config.
# note here that an ip address is used instead of the servce name in the MONGO_URL -
# this is a bug that I have to work out. To identify the IP address use docker network
# inspect web when the wekandb is running
environment:
- MONGO_URL=mongodb://172.xx.xx.2:27017/wekan
- ROOT_URL=http://wekan.myinternaldomain.org
- MAIL_URL=smtp://172.17.0.1:25/
- MAIL_FROM='Wekan Support - <unix.admin@myinternaldomain.org>'
# newer environment variables:
- BROWSER_POLICY_ENABLED=true
- TRUSTED_URL=''
- WEBHOOKS_ATTRIBUTES=''
depends_on:
- wekandb
volumes:
wekan-db:
driver: local
wekan-db-dump:
driver: local
networks:
web:
external: true
```
One this is done - run wekan with:
```
docker-compose up
```
This will run with logging output to the console - once its running ok - CTRL-C and start it up again with:
```
docker-compose up -d
```