Andreas/wekan
1
0
Fork 0
mirror of https://github.com/wekan/wekan.git synced 2026-01-09 19:18:50 +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

27
docs/Snap/Automatic-update-schedule.md Normal file
View file

@ -0,0 +1,27 @@
## a) Install all Snap updates automatically between 02:00AM and 04:00AM
```
snap set core refresh.schedule=02:00-04:00
```
## b) Update once a week at Sunday between 02:00AM and 04:00AM
```
snap set core refresh.schedule=sun,02:00-04:00
```
## c) Update last Sunday of the month between 02:00AM and 04:00AM
```
snap set core refresh.schedule=sun5,02:00-04:00
```
## [Update until specific day](https://snapcraft.io/docs/keeping-snaps-up-to-date#heading--refresh-hold) and other examples.
## If required, you can disable all Snap updates
at `/etc/hosts` by adding a line:
```
127.0.0.1 api.snapcraft.io
```
## No schedule set
Automatic upgrades happen sometime after Wekan is released, usually quite soon.
## Manual update immediately
`sudo snap refresh`

96
docs/Snap/Backup-and-restore.md Normal file
View file

@ -0,0 +1,96 @@
Also see [Docker Backup and Restore](https://github.com/wekan/wekan/wiki/Export-Docker-Mongo-Data)
# MongoDB client based backup
## Install MongoDB shell 3.2.x
[MongoDB 3.2.x shell for Ubuntu](https://docs.mongodb.com/v3.2/tutorial/install-mongodb-on-ubuntu/)
## Backup script for MongoDB Data, if running Snap MongoDB at port 27019
```sh
#!/bin/bash
now=$(date +'%Y-%m-%d_%H.%M.%S')
mkdir -p backups/$now
cd backups/$now
mongodump --port 27019
# if running on source install, run for example: mongodump --port 27017)
cd ..
zip -r $now.zip $now
cd ../..
echo "\nBACKUP DONE."
echo "Backup is at directory backups/${now}."
echo "Backup is also archived to .zip file backups/${now}.zip"
```
# Manual Backup
## Stop Wekan and Backup to directory called dump
```
sudo snap stop wekan.wekan
mongodump --port 27019
sudo snap start wekan.wekan
```
## Stop Wekan and Restore
```
sudo snap stop wekan.wekan
## Only if you get errors about existing indexes, use this instead:
## mongorestore -d wekan --drop --noIndexRestore --port 27019
mongorestore -d wekan --drop --port 27019
sudo snap start wekan.wekan
```
***
# Snap based backup (less reliable, can disappear with snap remove wekan)
## Setup backup directory
Create backup directory and set permissions
```
$ sudo mkdir /var/snap/wekan/common/db-backups
$ sudo chmod 777 /var/snap/wekan/common/db-backups
```
## Backup
As normal user as archive:
```
$ wekan.database-backup
```
Backup is created in directory:
```
/var/snap/wekan/common/db-backups
```
There is optional Backup file is optional parameter `$ wekan.database-backup BACKUPFILENAME`, but probably it does not work.
## List backups
You need to first create one backup, otherwise this command shows error.
To list existing backups in default directory, as normal user:
```
$ wekan.database-list-backups
```
## Restore backup
As normal user:
```
$ wekan.database-restore FULL-PATH-TO-BACKUP-FILENAME
```

276
docs/Snap/Candidate-WeKan-Snap-Manual-Upgrade.md Normal file
View file

@ -0,0 +1,276 @@
# NOTE: Using Candidate, that has MongoDB 6, that is newest version
Required time: If your database size is 500 GB, maybe 4 to 8 hours, or more. So bring enough of pizza, party snacks, limonade etc.
Warning: If you don't have enough disk space, you could get data loss.
Warning2: When starting WeKan Candidate, it could temporarily save all attachments to `/var/snap/wekan/common/files/` or other directory below `common`. That's why xet7 is working on trying to create separate migration app that moves attachments to S3, and that WeKan could upload to S3. This upgrade experience could be improved later. It's just that there are some unknown unknows if there would be automatic upgrade, could it handle all upgrade and migration cases.
If you are have time to try tro update Snap from WeKan Stable to newest WeKan Candidate, to see does update work or not.
If you have problems, add comment to issue https://github.com/wekan/wekan/issues/4780
## From WeKan Stable to Candidate
### Preparation
#### 1. Please read through all these below steps before starting, if possible.
#### 2. Check your database size, and do you have enough disk space for upgrade:
```
sudo du -sh /var/snap/wekan/common
df -h
```
For example, if your database size is 500 GB, and disk is nearly full, you need to stop WeKan and move to bigger disk. If disk gets full, there is possibility to MongoDB database corruption. Making mongodump could maybe take 2x of current size, or more.
Some external disk related steps are at https://github.com/wekan/wekan/wiki/Repair-MongoDB
#### 3. Problems usually are only, are attachments visible or not. Upgrade steps do not delete any files, if commands below are written correctly.
Optional steps:
a) Optionally, you could use [nosqlbooster](https://github.com/wekan/wekan/wiki/Backup#using-nosqlbooster-closed-source-mongodb-gui-with-wekan-snap-to-edit-mongodb-database) to save attachments to files, and export JSON to textfiles, before trying to update. There could also be files at `/var/snap/wekan/common/files` or other subdirectories. When saving attachments, note that there could be many files with same filename.
b) Optinally, you can also save [all database content to JSON](https://github.com/wekan/wekan/wiki/Export-from-Wekan-Sandstorm-grain-.zip-file#11b-dump-database-to-json-text-files), but if your database is about 500 GB then it could be too much disk space required, because attachments are at base64 encoded text in JSON files. It's better ot save attachments with [nosqlbooster](https://github.com/wekan/wekan/wiki/Backup#using-nosqlbooster-closed-source-mongodb-gui-with-wekan-snap-to-edit-mongodb-database).
#### 4. ssh to your server
```
ssh wekanserver
```
#### 5. Save snap settings and set it as executeable
```
sudo snap get wekan > snap-settings.sh
chmod +x snap-settings.sh
```
#### 6. Edit `snap-settings.sh` to look like this, with nano or similar
```
sudo snap set wekan root-url='https://wekan.example.com'
sudo snap set wekan port='80'
```
At nano, Save: Ctrl-o Enter
At nano. Exit: Ctrl-x
#### 7. Download newest MongoDB tools for your distro version that will work with MongoDB 5.x, but do not install it yet
https://www.mongodb.com/try/download/database-tools
For example, for Ubuntu 22.04, [mongodb-database-tools-ubuntu2204-x86_64-100.6.1.deb](https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2204-arm64-100.6.1.deb)
#### 8. Remove old versions of MongoDB tools etc, if you have those
List them:
```
dpkg -l | grep mongo
```
If that shows that you have old mongodb server also, check do you really use it, what is the size of database server files?
```
sudo du -sh /var/lib/mongodb
```
Do you have these files, or similar, that show where else mongodb raw database directory could be?
```
/etc/mongod.conf
/etc/mongod/mongod.conf
```
Try to connect to it, and see if there is anything?
```
mongo
```
If it does not connect, maybe start MongoDB database, for example some of these commands:
```
sudo systemctl enable mongod
sudo systemctl start mongod
sudo systemctl enable mongodb
sudo systemctl start mongod
sudo /etc/init.d/mongod start
```
Try then again connect, and view what is there. In this example, if there is wekan database listed with `show dbs`:
```
mongo
show dbs
use wekan
show collections
db.users.count()
db.users.find()
```
Also look is there `mongodb.list` packages repo?
```
sudo ls /etc/apt/sources.list.d/
```
If you have all of mongodb-org, try to remove all of them, with all related files:
```
sudo apt-get --purge remove mongo*
```
Delete mongodb repo:
```
sudo ls /etc/apt/sources.list.d/mongo*
sudo apt update
sudo apt clean
sudo apt -y autoclean
sudo apt -y autoremove
```
### Upgrade
#### 9. Stop wekan app
```
sudo snap stop wekan.wekan
```
#### 10. Use WeKan Stable Snap mongodump version for dumping database
```
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/snap/wekan/current/lib/x86_64-linux-gnu
export PATH="$PATH:/snap/wekan/current/bin"
mongodump --port 27019
```
#### 11. Move common directory contents. There are raw database files and maybe some attachments.
```
sudo snap stop wekan
sudo mkdir common
sudo mv /var/snap/wekan/common/* common/
sudo rm -rf /var/snap/wekan/common/*
```
#### 12. Change from Stable to Candidate
```
sudo snap refresh wekan --channel=latest/candidate
```
#### 13. Exit ssh and connect again, to not use old mongodump version anymore
```
exit
ssh wekanserver
```
#### 14. Install mongodb tools for your distro version (from [step 7](#7-download-newest-mongodb-tools-for-your-distro-version-that-will-work-with-mongodb-5x-but-do-not-install-it-yet) above)
```
sudo dpkg -i mongodb-database-tools-ubuntu2204-x86_64-100.6.1.deb
```
If there is any errors, please copy all text from install process to comment to issue https://github.com/wekan/wekan/issues/4780
When installing some package, if some dependendencies are missing, they can usually be installed with some of these commands, and installing continued with::
```
sudo apt-get -f install
sudo dpkg --configure -a
```
If you get this kind of error, it means you have existing version of MongoDB Tools still installed, you should remove all those like at step 7 above:
```
Unpacking mongodb-database-tools (100.6.1) ...
dpkg: error processing archive mongodb-database-tools-ubuntu2004-x86_64-100.6.1.deb (--install):
trying to overwrite '/usr/bin/bsondump', which is also in package mongo-tools 3.6.3-0ubuntu1
```
Sure there are options to force install this, for example this way, but not recommended:
```
sudo rm /usr/bin/bsondump
sudo dpkg -i ...
```
Or other not recommended way, forcing overwrite:
```
sudo dpkg -i --force-overwrite mongodb-database-tools-ubuntu2004-x86_64-100.6.1.deb
```
But better would be to use that [step 7](#7-download-newest-mongodb-tools-for-your-distro-version-that-will-work-with-mongodb-5x-but-do-not-install-it-yet) above to remove all old mongodb packages and repo, and then install MongoDB tools.
#### 15. Restore
```
sudo snap stop wekan
sudo snap start wekan.mongodb
mongorestore --drop --port 27019 --noIndexRestore
```
#### 16. Add back settings
Recommended is to use [Caddy 2](https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config) instead of Caddy1 that is included in WeKan Snap currently at 2022-12-21. Caddy 2 maybe will be included to WeKan Snap later.
See if in your `snap-settings.sh` is this kind of command, are you using Caddy1 ?
```
sudo snap set wekan caddy-enabled='true'
```
If you use Caddy1, and have any domain settings in your `common/Caddyfile`, copy it back:
```
sudo cp common/Caddyfile /var/snap/wekan/common/
```
At [step 6](#6-edit-snap-settingssh-to-look-like-this-with-nano-or-similar) above, you did create script that adds back snap settings. Run it to restore those settings:
```
./snap-settings.sh
```
You could also copy that file to common directory, if you like, or just keep it in your current directory:
```
sudo cp snap-settings.sh /var/snap/wekan/common/
```
#### 17. Start WeKan
```
sudo snap start wekan
```
#### 18. Test are WeKan attachments visible
#### 19. If you are using WeKan Snap Caddy1, if it does not work, change to Caddy2 https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config
#### 20. Backup and cleanup
Create archive of old files, and transer it to your local laptop, save somewhere safe:
```
ssh wekanserver
sudo su
7z a old-wekan.7z snap-settings.sh common dump
exit
scp wekanserver:/root/old-wekan.7z .
```
And then delete old files from server. Do not delete `snap-settings.sh`.
```
ssh wekanserver
rm -rf common dump
```
Also, keep [Daily Backups](https://github.com/wekan/wekan/wiki/Backup)
## Oops it did not work. From WeKan Candidate back to Stable
```
sudo snap stop wekan
sudo rm -rf /var/snap/wekan/common/*
sudo snap refresh wekan --channel=latest/stable
sudo snap stop wekan
sudo rm -rf /var/snap/wekan/common/*
sudo mv common/* /var/snap/wekan/common/
sudo snap start wekan
./snap-settings.sh
```
If you have problems, add comment to issue https://github.com/wekan/wekan/issues/4780
## From WeKan Gantt GPL to WeKan Candidate
- This is discontinued, Gantt features will be later added to WeKan MIT version.
- Gantt version files are instead at `/var/snap/wekan-gantt-gpl/`
- Gantt snap name is wekan-gantt-gpl

249
docs/Snap/CentOS-7.md Normal file
View file

@ -0,0 +1,249 @@
## CentOS 7 and RHEL7 and newer
Alternatives:
- Snap install like below. Automatic updates. Some time ago there were problems with [Snap on CentOS 7](https://github.com/wekan/wekan-snap/issues/103#issuecomment-571223099), that can result in updating not working properly, but that is a long time ago, and Snap version is currently 2020-04-29 installed at about 400 servers worldwide, according to Snap statistics that show only wordwide and per-country stats, not any more specific info. Please keep [daily backups](https://github.com/wekan/wekan/wiki/Backup).
- Docker or Bash/SystemD install from https://wekan.github.io
***
[Wekan snap bug reports and feature requests](https://github.com/wekan/wekan-snap/issues)
# Distro specific info how to install Snap on 64bit Linux
https://snapcraft.io
- CentOS 7, RHEL7 and newer, instructions below
# Install Wekan
### 1) Use root
```
sudo su
```
### 2) Install snap
2019-11-12 If instead of Caddy you use Nginx in front of Wekan on CentOS 7, you should
[disable selinux to prevent Nginx permission denied error](https://github.com/wekan/wekan/issues/2792).
2018-11-05 Also see [new snapd on EPEL](https://forum.snapcraft.io/t/snapd-updates-in-fedora-epel-for-enterprise-linux/8310).
Source: [Experimental CentOS7 snap](https://copr.fedorainfracloud.org/coprs/ngompa/snapcore-el7/) and [Forum post](https://forum.snapcraft.io/t/install-snapd-on-centos/1495/21)
```
yum makecache fast
yum install yum-plugin-copr epel-release
yum copr enable ngompa/snapcore-el7
yum install snapd
systemctl enable --now snapd.socket
```
### 3) Install Wekan. Set URL like (subdomain.)example.com(/suburl)
```
snap install wekan
snap set wekan root-url='https://boards.example.com'
```
[MORE ROOT-URL EXAMPLES](https://github.com/wekan/wekan/wiki/Settings)
### 4) Set port where Wekan runs, for example 80 if http, or local port 3001, if running behing proxy like Caddy
```
snap set wekan port='3001'
systemctl restart snap.wekan.wekan
```
### 5) Install all Snap updates automatically between 02:00AM and 04:00AM
```
snap set core refresh.schedule=02:00-04:00
```
Automatic upgrades happen sometime after Wekan is released, or at scheduled time, or with `sudo snap refresh`
### 6) Email and Other Settings
```
sudo snap set wekan mail-url='smtps://user:pass@mailserver.example.com:453'
sudo snap set wekan mail-from='Wekan Boards <support@example.com>'
```
[Troubleshooting Email](https://github.com/wekan/wekan/wiki/Troubleshooting-Mail)
## LDAP
See [Supported Settings Keys](Supported-settings-keys#ldap)
## [Matomo Web Analytics integration](Supported-settings-keys#matomo-web-analytics-integration)
See [Supported Settings Keys](Supported-settings-keys#matomo-web-analytics-integration)
## [Rocket.Chat providing OAuth2 login to Wekan](https://github.com/wekan/wekan/wiki/OAuth2)
Also, if you have Rocket.Chat using LDAP/SAML/Google/etc for logging into Rocket.Chat, then same users can login to Wekan when Rocket.Chat is providing OAuth2 login to Wekan.
# Optional: Install Caddy - Every Site on HTTPS
a) Personal non-commercial use only, included
b) Commercial use: see https://caddyserver.com/products/licenses
and [commercial usage issue](https://github.com/wekan/wekan-snap/issues/39),
contact Wekan maintainer x@xet7.org about how to enable commercial version
of caddy.
### 7) Add domain to Caddy config
```
nano /var/snap/wekan/common/Caddyfile
```
### 8) Replace first top line of text with (subdomain.)example.com(/suburl), without any beginning of http/https
Example Caddyfile config.
"alpn http/1.1" is because Firefox Inspect Console does not support http/2, so [turning it off](https://github.com/wekan/wekan/issues/934) so that Firefox would not show wss websocket errors. Chrome console supports http/2.
This uses free Let's Encrypt SSL. You can also use [free CloudFlare wildcard SSL or any other SSL cert](https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config).
```
boards.example.com {
tls {
alpn http/1.1
}
proxy / localhost:3001 {
websocket
transparent
}
}
```
Caddyfile example of static directory listing:
```
# Files have these permissions:
# chown root:root /var/snap/wekan/common/download.example.com
download.example.com {
root /var/snap/wekan/common/download.example.com
browse
}
```
[MORE Caddyfile EXAMPLES](https://github.com/caddyserver/examples)
### 9) Enable Caddy automatic https
```
snap set wekan caddy-enabled='true'
```
## 10) Reboot
## 11) Disable and enable wekan
```
$ sudo snap disable wekan
$ sudo snap enable wekan
```
If you use the mongodb port for another app, then, change it too:
```
$ sudo snap set wekan mongodb-port=27019
```
## 12) Add users
[Add users](https://github.com/wekan/wekan/wiki/Adding-users)
[Forgot Password](https://github.com/wekan/wekan/wiki/Forgot-Password)
## MongoDB CLI
1) Install MongoDB 3.2.x tools, and run on CLI:
`mongo --port 27019`
***
# Older install docs
```
$ sudo snap install wekan
```
IMPORTANT: SETUP [URL SETTINGS](#url-settings) BELOW, SO OPENING CARDS ETC WORKS CORRECTLY. More info at [Supported settings keys](Supported-settings-keys).
**IMPORTANT: Wekan Snap is bleeding edge, so any commits made to the wekan repository are pushed to the snap directly. Decide for yourself if you want to run wekan snap in production**
Make sure you have connected all interfaces, check more by calling
```
$ snap interfaces
```
Wekan has two services, to check status/restart/stop use systemd commands:
You can use these service commands:
- status
- start
- stop
- restart
MongoDB service:
```
$ sudo systemctl status snap.wekan.mongodb
```
Wekan service:
```
$ sudo systemctl status snap.wekan.wekan
```
## URL settings
[Nginx and Snap settings for https://example.com/wekan sub-url](https://github.com/wekan/wekan/wiki/Nginx-Webserver-Config)
Full URL to your Wekan, for example:
### Run Wekan on local network on selected port on computer IP address
```
$ sudo snap set wekan root-url='http://192.168.10.100:5000'
```
### Run Wekan only locally on selected port
```
$ sudo snap set wekan root-url='http://localhost:5000'
```
### Nginx or Caddy webserver in front of Wekan
[Nginx](https://github.com/wekan/wekan/wiki/Nginx-Webserver-Config) or [Caddy](https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config) is in front, full URL to real web address URL of Nginx or Caddy.
```
$ sudo snap set wekan root-url='https://example.com'
```
or
```
$ sudo snap set wekan root-url='https://example.com/wekan'
```
## Port settings
Localhost port where Wekan is running. This does not need to be exposed to Internet when running behind Nginx or Caddy.
```
$ sudo snap set wekan port='<your_port>'
```
## Restart Wekan after changes
```
$ sudo systemctl restart snap.wekan.wekan
```
When running without any additional settings, Wekan is at http://localhost:8080

20
docs/Snap/CentOS8.md Normal file
View file

@ -0,0 +1,20 @@
Using CentOS 8 Stream.
1. Install Snap https://snapcraft.io/docs/installing-snap-on-centos
2. Reboot
3. With terminal, test latest release candidate, to your server IP address:
```
su
snap install wekan --channel=latest/candidate
snap set wekan root-url='http://YOUR-IP-ADDRESS'
snap set wekan port='80'
```
4. For additional server options, see https://github.com/wekan/wekan/wiki/Settings
5. For adding users, see https://github.com/wekan/wekan/wiki/Adding-users
6. For other login option, see right menu at https://github.com/wekan/wekan/wiki

14
docs/Snap/Home.md Normal file
View file

@ -0,0 +1,14 @@
Welcome to the wekan-snap documentation wiki!
## Wekan snap at web
https://uappexplorer.com/snap/ubuntu/wekan
## Help command after installing
```
$ wekan.help
```
**All of commandline help is also in this wiki, categorized to their own wiki pages.**
See also [Wekan documentation](https://github.com/wekan/wekan/wiki)

15
docs/Snap/Install-snap-with-Ansible.md Normal file
View file

@ -0,0 +1,15 @@
## Ansible install by Pavel Stratil
[Info source](https://github.com/wekan/wekan/issues/1106)
## Original repos, please add feature requests there
https://github.com/Vaizard/mage-wekan
https://github.com/vaizard/mage-snapd
## Wekan's forked version
https://github.com/wekan/mage-wekan
https://github.com/wekan/mage-snapd

261
docs/Snap/Install.md Normal file
View file

@ -0,0 +1,261 @@
Snap for Linux, install to your own server or laptop. Automatic Updates. Only Standalone Wekan.
If on Snap Stable automatic update breaks something, [report Wekan for Snap bugs and feature requests here](https://github.com/wekan/wekan-snap/issues), so it can be fixed on some automatic update. If security is critical, keep behind firewall, without any ports open to Internet.
# Distro specific info how to install Snap on 64bit Linux
https://snapcraft.io
- Recommended: Newest 1) Ubuntu 2) Debian based distro
- Arch
- Fedora
- Solus
- OpenSUSE
- Gentoo
- Manjaro
- Elementary OS
- [CentOS 7, RHEL7 and newer](CentOS-7)
- [CentOS 8](CentOS8)
How ROOT_URL is set:
https://github.com/wekan/wekan/wiki/Settings
Here is how to add users:
https://github.com/wekan/wekan/wiki/Adding-users
How to switch between WeKan and WeKan Gantt GPL:
https://github.com/wekan/wekan/issues/2870#issuecomment-721364824
Newest Snap WeKan does not yet have migration to newest MongoDB. Here is how to try newer WeKan test candidate version, and migrate database manually:
https://github.com/wekan/wekan/issues/4505#issuecomment-1158380746
Below is how to install Snap.
# Install Wekan
### 1) Use root
```
sudo su
```
### 2) Install snap
a) Debian or Ubuntu
```
apt install snapd
```
b) Other distros
See [Snapcraft website](https://snapcraft.io).
### 3) Install Wekan. Set URL like (subdomain.)example.com(/suburl)
```
snap install wekan
snap set wekan root-url='https://wekan.example.com'
```
[MORE ROOT-URL EXAMPLES](https://github.com/wekan/wekan/wiki/Settings)
### 4) Set port where Wekan runs, for example 80 if http, or local port 3001, if running behing proxy like Caddy
```
snap set wekan port='3001'
systemctl restart snap.wekan.wekan
```
### 5) Install all Snap updates automatically between 02:00AM and 04:00AM
```
snap set core refresh.schedule=02:00-04:00
```
Update once a week at Sunday between 02:00AM and 04:00AM
```
snap set core refresh.schedule=sun,02:00-04:00
```
Update last Sunday of the month between 02:00AM and 04:00AM
```
snap set core refresh.schedule=sun5,02:00-04:00
```
[Update until specific day](https://snapcraft.io/docs/keeping-snaps-up-to-date#heading--refresh-hold) and other examples.
If required, you can disable all Snap updates at `/etc/hosts` by adding a line:
```
127.0.0.1 api.snapcraft.io
```
Automatic upgrades happen sometime after Wekan is released, or at scheduled time, or with `sudo snap refresh`
### 6) Email and Other Settings
```
sudo snap set wekan mail-url='smtps://user:pass@mailserver.example.com:453'
sudo snap set wekan mail-from='Wekan Boards <support@example.com>'
```
[Troubleshooting Email](https://github.com/wekan/wekan/wiki/Troubleshooting-Mail)
## LDAP
See [Supported Settings Keys](Supported-settings-keys#ldap)
## [Matomo Web Analytics integration](Supported-settings-keys#matomo-web-analytics-integration)
See [Supported Settings Keys](Supported-settings-keys#matomo-web-analytics-integration)
## [Rocket.Chat providing OAuth2 login to Wekan](https://github.com/wekan/wekan/wiki/OAuth2)
Also, if you have Rocket.Chat using LDAP/SAML/Google/etc for logging into Rocket.Chat, then same users can login to Wekan when Rocket.Chat is providing OAuth2 login to Wekan.
# Optional: Install Caddy - Every Site on HTTPS
### 7) Add domain to Caddy config
```
nano /var/snap/wekan/common/Caddyfile
```
### 8) Replace first top line of text with (subdomain.)example.com(/suburl), without any beginning of http/https
Example Caddyfile config.
"alpn http/1.1" is because Firefox Inspect Console does not support http/2, so [turning it off](https://github.com/wekan/wekan/issues/934) so that Firefox would not show wss websocket errors. Chrome console supports http/2.
This uses free Let's Encrypt SSL. You can also use [free CloudFlare wildcard SSL or any other SSL cert](https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config).
```
boards.example.com {
tls {
alpn http/1.1
}
proxy / localhost:3001 {
websocket
transparent
}
}
```
Caddyfile example of static directory listing:
```
# Files have these permissions:
# chown root:root /var/snap/wekan/common/download.example.com
download.example.com {
root /var/snap/wekan/common/download.example.com
browse
}
```
[MORE Caddyfile EXAMPLES](https://github.com/caddyserver/examples)
### 9) Enable Caddy automatic https
```
snap set wekan caddy-enabled='true'
```
## 10) Reboot
## 11) Disable and enable wekan
```
$ sudo snap disable wekan
$ sudo snap enable wekan
```
If you use the mongodb port for another app, then, change it too:
```
$ sudo snap set wekan mongodb-port=27019
```
## 12) Add users
[Add users](https://github.com/wekan/wekan/wiki/Adding-users)
[Forgot Password](https://github.com/wekan/wekan/wiki/Forgot-Password)
## MongoDB CLI
1) Install MongoDB 3.2.x tools, and run on CLI:
`mongo --port 27019`
***
# Older install docs
```
$ sudo snap install wekan
```
IMPORTANT: SETUP [URL SETTINGS](#url-settings) BELOW, SO OPENING CARDS ETC WORKS CORRECTLY. More info at [Supported settings keys](Supported-settings-keys).
**IMPORTANT: Wekan Snap is bleeding edge, so any commits made to the wekan repository are pushed to the snap directly. Decide for yourself if you want to run wekan snap in production**
Make sure you have connected all interfaces, check more by calling
```
$ snap interfaces
```
Wekan has two services, to check status/restart/stop use systemd commands:
You can use these service commands:
- status
- start
- stop
- restart
MongoDB service:
```
$ sudo systemctl status snap.wekan.mongodb
```
Wekan service:
```
$ sudo systemctl status snap.wekan.wekan
```
## URL settings
[Nginx and Snap settings for https://example.com/wekan sub-url](https://github.com/wekan/wekan/wiki/Nginx-Webserver-Config)
Full URL to your Wekan, for example:
### Run Wekan on local network on selected port on computer IP address
```
$ sudo snap set wekan root-url='http://192.168.10.100:5000'
```
### Run Wekan only locally on selected port
```
$ sudo snap set wekan root-url='http://localhost:5000'
```
### Nginx or Caddy webserver in front of Wekan
[Nginx](https://github.com/wekan/wekan/wiki/Nginx-Webserver-Config) or [Caddy](https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config) is in front, full URL to real web address URL of Nginx or Caddy.
```
$ sudo snap set wekan root-url='https://example.com'
```
or
```
$ sudo snap set wekan root-url='https://example.com/wekan'
```
## Port settings
Localhost port where Wekan is running. This does not need to be exposed to Internet when running behind Nginx or Caddy.
```
$ sudo snap set wekan port='<your_port>'
```
## Restart Wekan after changes
```
$ sudo systemctl restart snap.wekan.wekan
```
When running without any additional settings, Wekan is at http://localhost:8080

31
docs/Snap/Limit-snap-to-root-user-only.md Normal file
View file

@ -0,0 +1,31 @@
If you have some users logging to your server, that don't have root access, and you want to limit snap to root user only, you can do the following:
## 1) Set snap refresh schedule, for example
```
sudo snap set core refresh.schedule=02:00-03:00
```
## 2) Set cron to limit permissions to root users after updates
For example, sudo to root, and edit root cron with nano:
```
sudo su
export EDITOR=nano
crontab -e
```
and add there that at 03:10 permissions are limited to root again:
```
10 3 * * * chmod og-rwx /usr/bin/snap
10 3 * * * chmod -R og-rwx /var/snap
```
You can see crontab syntax help at https://crontab.guru
`snap` is the command, and `/var/snap` is where data is stored.
## Future snap features for permissions
For more advanced user permission control in snap, sometime new features will be added:<br />
https://forum.snapcraft.io/t/multiple-users-and-groups-in-snaps/1461/3

54
docs/Snap/Making-releases-from-source.md Normal file
View file

@ -0,0 +1,54 @@
# Installing snapcraft from source
This is old and already fixed, was only needed when [snap build servers were broken](https://github.com/wekan/wekan-snap/issues/58) and [snapcraft had bug](https://forum.snapcraft.io/t/permission-denied-when-building-with-snapcore-snapcraft/7186/14?u=xet7) that has [fix that was not released to snap channel yet](https://github.com/snapcore/snapcraft/pull/2240). All this is fixed now.
So I removed snap version, and installed snapcraft from source, and it seems to work for me.
## Snapcraft source install on Ubuntu 16.04 64bit
Add to /root/.bashrc:
```
export PATH="$PATH:/home/user/repos/snapcraft/bin"
```
## Install dependencies
```
sudo apt install python3-yaml python3-tabulate python3-pymacaroons \
python3-progressbar python3-requests-unixsocket python3-petname \
python3-pyelftools python3-click python3-simplejson \
python3-requests-toolbelt python3-jsonschema xdelta3
```
## Install snapcraft
```
cd ~/repos
git clone https://github.com/snapcore/snapcraft.git
cd snapcraft
sudo python3 setup.py install
```
## [Workaround bug](https://bugs.launchpad.net/snapcraft/+bug/1656884/comments/1)
```
sudo ln -s /usr/local/lib/python3.5/dist-packages/snapcraft-2.43-py3.5.egg/share/snapcraft/ /usr/share/snapcraft
```
## Build package
```
cd ~/repos/wekan
sudo snapcraft
```
## Install snap package locally to test it
```
sudo snap install --dangerous wekan_1.*_amd64.snap
```
## Changing back to stable or edge snap
https://github.com/wekan/wekan-snap/wiki/Snap-Developer-Docs
## Login to snapcraft
If you have access to publishing snaps.
## Push package to snap store
```
sudo snapcraft push wekan_1.*_amd64.snap
```
## Publish at snap store
https://dashboard.snapcraft.io/dev/snaps/7867

9
docs/Snap/Making-releases.md Normal file
View file

@ -0,0 +1,9 @@
## Triggering git import process manually
https://code.launchpad.net/~wekan-team/wekan/+git/wekan
## When ready, uploaded to store. Check and release.
Once you snap is uploaded you should see it here:
https://dashboard.snapcraft.io/dev/snaps/7867

466
docs/Snap/Many-Snaps-on-LXC.md Normal file
View file

@ -0,0 +1,466 @@
https://github.com/wekan/wekan-snap/wiki/Many-Snaps-on-LXC#lxd-init-cidr
# NEW WAY: Parallel Snap Installs
Note: This presumes that your laptop runs newest Ubuntu or Kubuntu, and that server is Ubuntu.
1) Install Caddy2 https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config
2) Optional, recommended: Encrypted VM. Idea: Bare Metal Caddy => Proxy to encrypted VM ports => Each customer separate Snap WeKan port. Snap sandbox files at /common, snap code can not access files outside of it's /common directories. Newest WeKan is Snap Candidate. Snap has automatic updates.
2.1) If your server has additional harddrives, format them:
```
ls /dev
mkfs.ext4 /dev/nvme0n1
```
2.2) Look at that above command text output, what is created disk UUID. Add those to /etc/fstab:
```
UUID=12345-678-90 /data ext4 errors=remount-ro 0 1
```
2.3) Create directories for mounting disk, and mount all drives:
```
sudo su
cd /
mkdir /data
mount -a
```
2.4) Install to your laptop and bare metal server packages for using remote desktop with KVM:
```
sudo apt install virt-manager qemu-system
```
2.5) Check that you can ssh to server with ssh public key as root. For that, create ssh key on your laptop, press enter many times until it's done:
```
ssh-keygen
```
2.6) copy laptop .ssh/id_rsa.pub content to server /root/.ssh/authorized_keys .
2.7) At server disable password login at /etc/ssh/sshd_config , password login enabled false. And `sudo systemctl restart ssh`
2.8) At your laptop edit .ssh/config , there add your server IP address etc. This server here is named x1.
```
Host x1
Hostname 123.123.123.123
User root
IdentityFile ~/.ssh/id_rsa
```
2.9) Check that you can ssh from laptop to server as root without prompts.
2.10) Start virt-manager GUI at your laptop:
- File / Add connection
- Hypervisor: QEMU/KVM
- [X] Connect to remote host via SSH
- Username: root
- Machine name: x1
- Connect automatically: [X]
- Click [Connect]
2.11) AT SERVER: Create harddrive image: `qemu-img create -f qcow2 web.qcow2 700G`
2.12) Download newest Kubuntu desktop iso with wget.
2.13) Install kubuntu with full disk encryption. Modify amount of RAM (here 32 GB), file locations etc. Do not select to allocate encrypted disk image immediately, let image size grow.
2.14) Create growing disk with max size:
```
qemu-img create -f qcow2 web.qcow2 700G
```
2.15) Start install from .iso image. Here RAM -r 32 GB, name web, change disk and iso locations below, vcpu 20 (check your server with nproc, should be less that all):
```
sudo virt-install -r 32000 -n web --os-type=linux --os-variant=ubuntu16.04 \
--disk /data/VMs/web.qcow2,device=disk,format=qcow2 \
-c /data/VMs/iso/kubuntu-22.10-desktop-amd64.iso \
--vcpus=20 --vnc --noautoconsole
```
It will appear to your laptop virt-manager GUI.
If you have shutdown KVM VM, you can start it from virt-manager, or this way without .iso image:
```
sudo virt-install -r 32000 -n web --boot hd --video=vga --os-type=linux --os-variant=ubuntu16.04 \
--disk /data/VMs/web.qcow2,device=disk,format=qcow2 \
--vcpus=20 --vnc --noautoconsole
```
3) Use Parallel Snap installs https://snapcraft.io/docs/parallel-installs
For example:
```
sudo snap set system experimental.parallel-instances=true
```
4) With newest WeKan Candidate like https://github.com/wekan/wekan-snap/wiki/CentOS8 . Note: Each user has different wekan port and mongodb port.
```
sudo snap install wekan --channel=latest/candidate
sudo snap install wekan wekan_customer1 --channel=latest/candidate
sudo snap disable wekan
sudo snap set wekan_customer1 caddy-enabled='false'
```
Check that each WeKan uses candidate:
```
sudo snap list
```
If not, change to candidate:
```
sudo snap refresh wekan_customer1 --channel=latest/candidate
```
If it complains about old database version (was at stable), stop it, move old files somewhere safe, and start again.
WARNING: this deletes
```
sudo su
mkdir old_customer1_common
snap stop wekan_customer1
mv /var/snap/wekan_customer1/common/* old_customer1_common/
snap start wekan_customer1
```
5) Add some settings, for example Google login and [AWS SES email sending](https://github.com/wekan/wekan/wiki/Troubleshooting-Mail#example-aws-ses):
For each customer, node and mongodb needs to be in different ports, for example:
```
sudo snap set wekan_customer1 port='5001'
sudo snap set wekan_customer1 mongodb-port='25001'
sudo snap set wekan_customer2 port='5002'
sudo snap set wekan_customer2 mongodb-port='25002'
```
For customer1:
```
sudo snap set wekan_customer1 port='5001'
sudo snap set wekan_customer1 mongodb-port='25001'
sudo snap set wekan_customer1 root-url='https://wekan.customer1.com'
sudo snap set wekan_customer1 mail-url='smtp://username:password@email-smtp.eu-west-1.amazonaws.com:587?tls={ciphers:"SSLv3"}&secureConnection=false'
sudo snap set wekan_customer1 mail-from='Wekan Customer1 Support <board@customer1.com>'
sudo snap set wekan_customer1 oauth2-auth-endpoint='https://accounts.google.com/o/oauth2/v2/auth'
sudo snap set wekan_customer1 oauth2-client-id='YOUR-GOOGLE-LOGIN-CLIENT_ID.apps.googleusercontent.com'
sudo snap set wekan_customer1 oauth2-secret='YOUR-GOOGLE-LOGIN-SECRET'
sudo snap set wekan_customer1 oauth2-email-map='email'
sudo snap set wekan_customer1 oauth2-enabled='true'
sudo snap set wekan_customer1 oauth2-fullname-map='name'
sudo snap set wekan_customer1 oauth2-id-map='sub'
sudo snap set wekan_customer1 oauth2-request-permissions='openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email'
sudo snap set wekan_customer1 oauth2-token-endpoint='https://oauth2.googleapis.com/token'
sudo snap set wekan_customer1 oauth2-userinfo-endpoint='https://openidconnect.googleapis.com/v1/userinfo'
sudo snap set wekan_customer1 oauth2-username-map='nickname'
```
You can check with [nosqlbooster](https://github.com/wekan/wekan/wiki/Backup#using-nosqlbooster-closed-source-mongodb-gui-with-wekan-snap-to-edit-mongodb-database) that each database has correct data.
When restoring data, stop that wekan, and restore to that port, when you have subdirectory dump:
```
sudo snap stop wekan_customer2.wekan
mongorestore --drop --port 25002
sudo snap start wekan_customer2.wekan
```
If there is errors, try again without restoring indexes:
```
mongorestore --drop --noIndexRestore --port 25002
```
To empty database, use [mongodb shell](https://www.mongodb.com/try/download/shell):
```
mongosh --port 25002
show dbs
use wekan
db.dropDatabase()
```
To see is settings written correctly, use:
```
sudo snap get wekan_customer1
sudo snap get wekan_customer2
```
And that at `Caddyfile` each subdomain is proxied to correct port like 3001 etc.
And that if there is snap called wekan, it's not in use:
```
sudo snap disable wekan
```
or has different port:
```
sudo snap get wekan
sudo snap set wekan port='6001'
sudo snap set wekan mongodb-port='28001'
```
6) Example backup script, that backups MongoDB databases. Although, maybe files directories needed to be added too.
Note: Here customer1 likes to get backup copy of backups, so this copies customer1 backup to separate directory that is synced only to that customer with Syncthing. Via email was asked customer syncthing ID, and added sync.
Set it as executeable:
```
chmod +x backup.sh
```
To run it:
```
sudo su
cd backup
./backup.sh
```
Here is backup.sh, using [mongodb tools](https://www.mongodb.com/try/download/database-tools) for mongodump/mongorestore etc:
```
#!/bin/bash
# Backup all MongoDB databases from different ports.
# Note: You may need to check also is there files directory,
# and also backup that, like /var/snap/wekan/common/files etc
function backup {
cd /home/wekan/backup
# >> /home/wekan/backup/backup-log.txt
mkdir -p /home/wekan/backup/new/$1
cd /home/wekan/backup/new/$1
mongodump --port $2
sudo snap get wekan_$1 > snap-settings.txt
cd ..
7z a $(date -u +$1-wekan-backup-%Y-%m-%d_%H.%M_UTC.7z) $1
mkdir /home/wekan/$3
chown wekan:wekan *.7z
mv *.7z /home/wekan/$3/
rm -rf $1
cd /home/wekan/backup
}
function backupchat {
cd /home/wekan/backup >> /home/wekan/backup/backup-log.txt
mkdir -p /home/wekan/backup/new/$1 >> /home/wekan/backup/backup-log.txt
cd /home/wekan/backup/new/$1 >> /home/wekan/backup/backup-log.txt
mongodump >> /home/wekan/backup/backup-log.txt
cd ..
7z a $(date -u +$1-backup-%Y-%m-%d_%H.%M_UTC.7z) $1
mkdir /home/wekan/$3
chown wekan:wekan *.7z
mv *.7z /home/wekan/$3/
rm -rf $1
cd /home/wekan/backup
}
# Syntax:
# backup customername port backupdir
function websync {
# Backup WeKan Kanban Snaps to different Syncthing sync directories
backup "customer1" "25001" "backup-wekan-customer1"
backup "customer1" "25001" "websync"
backup "customer2" "25002" "websync"
backup "customer3" "25003" "websync"
backup "customer4" "25004" "websync"
backup "customer5" "25005" "websync"
# Backup RocketChat Snap
backupchat "chat" "27027" "websync"
cd ~/websync
## backup the backup scripts
# 7z a $(date -u +wekan-backup-scripts-%Y-%m-%d_%H.%M_UTC.7z) ~/backup
}
(websync) >> /home/wekan/backup/backup-log.txt 2>&1
```
7. At bare metal server is installed [Caddy2](https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config).
Each customer has set in their nameserver to WeKan hosting server IP address:
```
A 123.123.123.123
```
After that, when ping wekan.company1.com shows 123.123.123.123 correctly, it's possible to get
automatic Let's Encrypt SSL/TLS cert with Caddy2.
At encrypted KVM VM type `ip address`, it shows what is KVM VM internal IP address.
Caddy2 proxies with Let's Encrypt TLS HTTPS to encrypted VM HTTP IP address and port where WeKan (Node.js) is running.
/etc/caddy/Caddyfile . Examples when in /etc/caddy directory as root: `caddy start`, `caddy stop`, `caddy validate`, `caddy --help`
```
(redirect) {
@http {
protocol http
}
redir @http https://{host}{uri}
}
kanban.customer1.com {
tls {
alpn http/1.1
}
reverse_proxy 192.168.123.23:5001
}
kanban.customer2.com {
tls {
alpn http/1.1
}
reverse_proxy 192.168.123.23:5002
}
```
Other non-kanban examples:
```
# Static website that uses free CloudFlare TLS certificates
company.com {
tls {
load /data/websites/certificates/company
alpn http/1.1
}
root * /data/websites/company.com
file_server
}
# RocketChat
chat.company.com {
tls {
alpn http/1.1
}
reverse_proxy 192.168.123.23:3000
}
# Browseable files listing static website
files.company.com {
tls {
alpn http/1.1
}
root * /data/websites/files.company.com
file_server browse
}
```
***
# OLD WAY: Many Snaps on LXC
## LXD init CIDR
IPv4 CIDR: 10.1.1.1/24
```
sudo apt install snapd
sudo reboot
sudo snap install lxd
lxd init
Would you like to use LXD clustering? (yes/no) [default=no]:
Do you want to configure a new storage pool? (yes/no) [default=yes]:
Name of the new storage pool [default=default]:
Name of the storage backend to use (dir, lvm, btrfs, ceph) [default=btrfs]: dir
Would you like to connect to a MAAS server? (yes/no) [default=no]:
Would you like to create a new local network bridge? (yes/no) [default=yes]:
What should the new bridge be called? [default=lxdbr0]:
What IPv4 address should be used? (CIDR subnet notation, “auto” or “none”) [default=auto]: 10.1.1.1/24
Would you like LXD to NAT IPv4 traffic on your bridge? [default=yes]:
What IPv6 address should be used? (CIDR subnet notation, “auto” or “none”) [default=auto]:
Would you like the LXD server to be available over the network? (yes/no) [default=no]:
Would you like stale cached images to be updated automatically? (yes/no) [default=yes]:
Would you like a YAML "lxd init" preseed to be printed? (yes/no) [default=no]:
```
> The value you have specified is the “network address”, i.e “.0” is the network address of the subnet “10.1.1.0/24”. Instead you need to specify an IP in that network, such as “.1”, e.g. “10.1.1.1/24”
https://discuss.linuxcontainers.org/t/failed-lxd-init-what-is-cidr/7181/2
## 1) Main Snap on bare metal
[Install Wekan Snap](Install) to newest Ubuntu bare metal server. Snaps have automatic updates.
For example:
```
sudo apt-get install snapd
reboot
sudo snap install wekan
```
For Let's Encrypt SSL, like this to `/var/snap/wekan/common/Caddyfile`. We will be proxying to inside LXD container:
```
boards.example.com {
tls {
alpn http/1.1
}
proxy / 10.10.10.231:3001 {
websocket
transparent
}
}
```
For [CloudFlare SSL](https://github.com/wekan/wekan/wiki/Caddy-Webserver-Config), like this to `/var/snap/wekan/common/Caddyfile`:
```
http://boards.example.com https://boards.example.com {
tls {
load /var/snap/wekan/common/certificates
alpn http/1.1
}
proxy / 10.10.10.231:3001 {
websocket
transparent
}
}
```
## 2) New LXC container
So when I start new lxc container:
```
lxc launch images:ubuntu/20.04 lxccontainername
```
## 3) Snapd and Wekan
Then I go inside container and install snapd:
```
lxc exec lxccontainername -- /bin/bash
apt -y install snapd
reboot
lxc exec lxccontainername -- /bin/bash
snap install wekan
snap set wekan root-url='https://boards.example.com'
sudo snap set wekan port='3001'
sudo snap set wekan mail-from='Wekan Team Boards <info@example.com>'
sudo snap set wekan mail-url='smtps://username:password@email-smtp.eu-west-1.amazonaws.com:587'
ip address
exit
```
That `ip address` command does show current IP address of container, that you can then add to bare metal `/var/snap/wekan/common/Caddyfile`.
You can also add more lxc containers to different subdomains and proxy to them in main Caddyfile.
## 4) Some LXC commands
### New Ubuntu container
```
lxc launch images:ubuntu/20.04 lxccontainername
```
### Inside LXC container
```
lxc exec lxccontainername -- /bin/bash
```
### Running command in LXC
```
lxc exec lxccontainername -- apt install p7zip-full
```
### Limit RAM available to LXC
```
lxc config set lxccontainername limits.memory 4GB
```
### New Debian container
```
lxc launch images:debian/buster mydebiancontainername
```
### New CentOS 7 container
```
lxc launch images:centos/7/amd64 centos
```
### List containers
```
lxc list -cns
```
Result:
```
+---------------+---------+
| NAME | STATE |
+---------------+---------+
| mycontainer | RUNNING |
+---------------+---------+
```
### Stop and delete container
```
lxc stop mycontainer
lxc delete mycontainer
```

78
docs/Snap/Old-Making-releases.md Normal file
View file

@ -0,0 +1,78 @@
# Older way to make releases, does not work.
***
## Triggering git import process manually
[Info source](https://github.com/wekan/wekan-snap/issues/2#issuecomment-311324364)
To make build quicker, it's possible to trigger git import process manually in launchpad, so you don't need to wait for next sync.
https://code.launchpad.net/~wekan-team/wekan/+git/wekan
## Launchpad project
[Info source](https://github.com/wekan/wekan-snap/pull/3#issuecomment-310764751)
kubiko created launchpad wekan project and wekan team where xet7 is admin in and contributor. xet7 can feel free to add other people on the list.
Wekan project has wekan-snap repo mirrored from github one:
https://code.launchpad.net/~wekan-team/wekan/+git/wekan-snap
Sync happens every ~5 hours
There is snap package enabled for this repo which has automatic build upon change in repo enabled, you can see there also build queue:
https://code.launchpad.net/~wekan-team/+snap/wekan-devel
It has also auto push to store enabled, so once built snap is uploaded to candidate channel.
Once you snap is uploaded you should see it here:
https://dashboard.snapcraft.io/dev/snaps/7867
kubiko got email from launchpad account and added xet7 as collaborator list, so xet7 can control promotion to stable channel once candidate version is tested. There xet7 can see there some other interesting stats about snap adoption.
For the future once xet7 makes change in wekan-snap build and upload should happen automatically, no need for additional interaction.
Next thing for kubiko would be to move people from wekan-ondra to wekan, not quite sure how to announce this though….. From stats kubiko did see there are ~320 downloads/installs of version 0.23.
kubiko also created pull request to wekan repo, which enabled continuous integration from master, typically this would be pushing builds to edge channel, from where xet7 can do testing, or more adventures users can use edge channel to track Wekan master branch….
## Snapcraft build support from source
[Info source](https://github.com/wekan/wekan/pull/1091)
Adding snapcraft build support. This can be used together with launchpad build system for continuous integration.
Intention is to push snaps build from devel branch to edge channel, which can be installed by calling:
```
$ snap install -edge wekan
```
device will keep automatically updating to revisions as they are released to edge channel
@xet7 Snap build job is now created, you can see it here:
https://code.launchpad.net/~wekan-team/+snap/wekan-devel
It's building from devel branch, fee free to change that if you prefer it to build from different branch.
Same as for release apply here, auto builds on change, only resulting snap is pushed to edge channel instead.
Also check please version name if you want it to be something different than:
```
0.26-SNAPSHOT
```
## Old links, not in use
( Old trigger git import https://code.launchpad.net/~wekan-team/wekan/+git/wekan-snap )
( Old build queue, not in use: https://code.launchpad.net/~wekan-team/+snap/wekan-release )
( Old build queue, not in use: https://code.launchpad.net/~ondrak/+snap/wekan-devel )

1
docs/Snap/OpenSuse.md Normal file
View file

@ -0,0 +1 @@
https://github.com/wekan/wekan/wiki/OpenSuse

14
docs/Snap/Sharing-MongoDB.md Normal file
View file

@ -0,0 +1,14 @@
## Share MongoDB to other snaps
- connect mongodb-slot with plug from corresponding snap(s)
- configure corresponding service to use mongodb unix socket in shared directory, socket file name is: mongodb-.sock
## Sharing MongoDB from other snap to wekan
- connect mongodb-plug with slot from snap providing mongodb
- disable mongodb in wekan by calling:
```
$ snap set wekan set disable-mongodb='true'
```
- set mongodb-bind-unix-socket to point to serving mongodb. Use relative path inside shared directory, e.g run/mongodb-27017.sock

125
docs/Snap/Supported-settings-keys.md Normal file
View file

@ -0,0 +1,125 @@
Wekan supports settings key values:
```
$ snap set wekan <key name>='<key value>'
```
## List all possible settings
```
$ wekan.help | less
```
## List your current snap settings
```
sudo snap get wekan
```
## LDAP
- Settings can be seen with command `wekan.help` and [this config file](https://raw.githubusercontent.com/wekan/wekan/master/snap-src/bin/config).
- LDAP repo https://github.com/wekan/wekan-ldap
- Bugs and Feature Requests LDAP repo https://github.com/wekan/wekan-ldap/issues
Example from setting listed at [this config file](https://raw.githubusercontent.com/wekan/wekan/master/snap-src/bin/config):
```
sudo snap set wekan ldap-enable='true'
sudo snap set wekan default-authentication-method='ldap'
sudo snap set wekan ldap-fullname-field='CN'
```
## List of supported keys
```
mongodb-bind-unix-socket: mongodb binding unix socket:
Default behaviour will preffer binding over unix socket, to
disable unix socket binding set value to 'nill' string
To bind to instance of mongodb provided through content
interface, set value to relative path to the socket inside
'shared' directory.
Default value: set to use unix socket binding
mongodb-bind-ip: mongodb binding ip address: eg 127.0.0.1 for localhost
If not defined default unix socket binding is used instead
Default value: ''
mongodb-port: mongodb binding port: eg 27017 when using localhost
Default value: '27019'
mail-url: wekan mail binding
Example: 'smtps://user:pass@mailserver.examples.com:453/'
Default value: 'smtp://user:pass@mailserver.examples.com:25/'
mail-from: wekan's admin mail from name email address
For example: 'Boards Support <support@example.com>'
Default value: 'wekan-admin@example.com'
root-url: wekan's root url, eg http://127.0.0.1, https://example.com,
https://wekan.example.com, http://example.com/wekan
Default value: 'http://127.0.0.1'
port: port wekan is exposed at
Default value: '8080'
disable-mongodb: Disable mongodb service: use only if binding to
database outside of Wekan snap. Valid values: [true,false]
Default value: 'false'
caddy-enabled: Enable caddy service (caddy - Every Site on HTTPS).
see https://caddyserver.com/products/licenses and
https://github.com/wekan/wekan-snap/issues/39 ,
use personal non-commercial license or
contact Wekan maintainer x@xet7.org about enabling
commercial license for Caddy.
Set to 'true' to enable caddy.
caddy settings are handled through
/var/snap/wekan/common/Caddyfile
Default value: 'false'
caddy-bind-port: Port on which caddy will expect proxy, same value
will be also set in Caddyfile
Default value: '3001'
with-api: To enable the API of wekan. If API is disabled,
exporting board to JSON does not work.
Default value: 'true'
cors: Set Access-Control-Allow-Origin header. Example:
snap set wekan cors='*'
Default value, disabled: ''
browser-policy-enabled: Enable browser policy and allow one
trusted URL that can have iframe that has
Wekan embedded inside.
Setting this to false is not recommended,
it also disables all other browser policy protections
and allows all iframing etc. See wekan/server/policy.js
Default value: 'true'
trusted-url: When browser policy is enabled, HTML code at this URL
can have iframe that embeds Wekan inside.
Example: trusted-url='https://example.com'
Default value: ''
webhooks-attributes: What to send to Outgoing Webhook, or leave out.
Example, that includes all that are default:
cardId,listId,oldListId,boardId,comment,user,card,commentId .
To enable the Webhooks Attributes of Wekan:
snap set wekan webhooks-attributes=cardId,listId,oldListId,boardId,comment,user,card,commentId
Disable the Webhooks Attributest of Wekan to send all default ones:
snap set wekan webhooks-attributes=''
```
## Rocket.Chat providing OAuth2 login to Wekan
Also, if you have Rocket.Chat using LDAP/SAML/Google/etc for logging into Rocket.Chat, then same users can login to Wekan when Rocket.Chat is providing OAuth2 login to Wekan.
[OAuth2 Login Docs](https://github.com/wekan/wekan/wiki/OAuth2)
## [Matomo web analytics](https://matomo.org) integration
Example:
```
sudo snap set wekan matomo-address='https://matomo.example.com/'
sudo snap set wekan matomo-site-id='25'
sudo snap set wekan matomo-with-username='true'
sudo snap set wekan matomo-do-not-track='false'
```
Matomo settings keys:
```
matomo-address: The address of the server where matomo is hosted
No value set, using default value: ''
matomo-site-id: The value of the site ID given in matomo server for wekan
No value set, using default value: ''
matomo-do-not-track: The option do not track which enables users to not be tracked by matomo
Current value set to: 'true', (default value: 'true')
matomo-with-username: The option that allows matomo to retrieve the username
Current value set to: 'false', (default value: 'false')
```
**When settings are changed, wekan/mongo/caddy services are automatically restarted for changes to take effect.**

81
docs/Snap/Testing-new-WeKan-Snap-versions.md Normal file
View file

@ -0,0 +1,81 @@
Please:
- Test does WeKan on some non-stable channel work, [add a new issue](https://github.com/wekan/wekan-snap/issues) about can it be added to stable channel.
- Check [is there PR about fixing some bug already](https://github.com/wekan/wekan/pulls)
- Please report bugs [by adding a new issue](https://github.com/wekan/wekan-snap/issues).
- Make backups first, so you are not using your only copy of production data
- Have time to test
- Have enough disk space. For example, some update migration could write all attachments from database to some subdirectory of `/var/snap/wekan/common` or `/var/snap/wekan-gantt-gpl/common`.
- You can try bleeding edge versions of Wekan Snap, that contains cool new features, and could be broken in many ways.
- Sometimes Snap builds fail, so then there is no package file to upload to Snap store at all, only successfully built are visible at Snap store. Successfully built does not mean that every feature works.
[Changing between WeKan and WeKan Gantt GPL](https://github.com/wekan/wekan/issues/2870#issuecomment-721364824)
## 1) Stop WeKan
```
sudo snap stop wekan
```
or
```
sudo snap stop wekan-gantt-gpl
```
## 2) Create Backup
2.1 Backup settings:
```
sudo snap get wekan > snap-settings.txt
```
or
```
sudo snap get wekan-gantt-gpl > snap-settings.txt
```
2.2 https://github.com/wekan/wekan/wiki/Backup
2.3 Copy files to safe place from /var/snap/wekan/common or /var/snap/wekan-gantt-gpl/common . There could be some board attachments etc.
## 3) Check what is available at various channels
https://snapcraft.io/wekan
https://snapcraft.io/wekan-gantt-gpl
- Stable: Current working version
- Beta: Maybe work, or not
- Edge: Newest that did build, no idea does it work or not
This is how you can try snap beta channel:
```
sudo snap refresh wekan --beta --amend
```
This is how to change back to snap stable channel, that most Wekan users have installed:
```
sudo snap refresh wekan --stable --amend
```
Wekan stable versions are numbered v1.x
## 4) Update all Snaps to newest on that channel
[Check you don't have Snap updates disabled](Automatic-update-schedule#if-required-you-can-disable-all-snap-updates)
```
sudo snap refresh
```
## 5) Start WeKan
```
sudo snap stop wekan
```
or
```
sudo snap stop wekan-gantt-gpl
```
## Other docs
* [Adding Snap settings to code](https://github.com/wekan/wekan/wiki/Adding-new-Snap-settings-to-code)
* [Wekan Developer Docs](https://github.com/wekan/wekan/wiki/Developer-Documentation)

65
docs/Snap/Troubleshooting.md Normal file
View file

@ -0,0 +1,65 @@
[Info source](https://github.com/wekan/wekan-snap/issues/4#issuecomment-311355296)
1) All you need to do is
```
$ snap install wekan
```
2) Enable/disable is not needed, it is there for cases when for example you want to stop wekan, but do not want to uninstall it (uninstall will delete also all user data)
3) Wekan is service, so apart of help, it does not have any "user executables"
4) You can check status of wekan with:
```
$ sudo systemctl status snap.wekan.*
```
there should be two services, mongodb and wekan running, of either of them is showing error, that would be place to look first. To get detailed look, use
```
$ sudo journalctl -u snap.wekan.*
```
or detailed look of one of services:
```
$ sudo journalctl -u snap.wekan.wekan.service
```
or
```
$ snap.wekan.mongodb.service
```
5) Content interface for mongodb (wekan:mongodb-slot, wekan:mongodb-plug) is there only for more complex cases where for reason you want to:
a) share wekan's mongodb instance with other services, use wekan:mongodb-slot
b) you want to use mongodb instance from some other service, use wekan:mongodb-plug
so connecting wekan:mongodb-plug to wekan:mongodb-slot really makes no sense :)
As @xet7 suggested, first thing to make sure is that update your machine, so you are running up to date snapd. You can check your version with
```
$ snap version
```
Currently we are on 2.26
Otherwise shared folders are created under:
```
/var/snap/wekan/current where writable data lives
```
Databases and other settings live under:
```
/var/snap/wekan/common/
/snap/wekan/current is read only mount of squashfs wekan's image.
```
[Troubleshooting Email](https://github.com/wekan/wekan/wiki/Troubleshooting-Mail)

54
docs/Snap/Uninstall.md Normal file
View file

@ -0,0 +1,54 @@
List what snaps you have installed. Core is part of snap itself.
```
sudo snap list
```
List what snap services are running:
```
sudo snap services
```
Uninstall Wekan snap and delete all Wekan data. If you have other snaps installed, you can remove them too. Don't remove core, it's part of snap itself.
```
sudo snap stop wekan
sudo snap disable wekan
sudo snap remove wekan
```
OPTIONAL ALTERNATIVE WAY, NOT REQUIRED: Disable some services of wekan using systemd:
```
sudo systemctl stop snap.wekan.wekan
sudo systemctl stop snap.wekan.mongodb
sudo systemctl stop snap.wekan.caddy
sudo systemctl disable snap.wekan.wekan
sudo systemctl disable snap.wekan.mongodb
sudo systemctl disable snap.wekan.caddy
```
Uninstall snap at CentOS:
```
sudo systemctl disable --now snapd.socket
sudo yum copr disable ngompa/snapcore-el7
sudo yum remove yum-plugin-copr snapd
```
Uninstall snap at Debian/Ubuntu/Mint:
```
sudo systemctl stop snapd
sudo systemctl disable snapd
sudo apt --purge remove snapd
```
Uninstall snap at [Ubuntu 14.04](https://github.com/wekan/wekan-snap/issues/34#issuecomment-378295168):
```
sudo service snapd stop
sudo update-rc.d -f snapd remove
sudo apt-get --purge remove snapd
```

5
docs/Snap/Update-all-snap-packages.md Normal file
View file

@ -0,0 +1,5 @@
Update all snap packages, like Wekan and others, with commmand:
```
sudo snap refresh
```