diff --git a/Installing-on-OpenBSD-7.6.md b/Installing-on-OpenBSD-7.6.md new file mode 100644 index 0000000..c7d0ad3 --- /dev/null +++ b/Installing-on-OpenBSD-7.6.md @@ -0,0 +1,115 @@ +# Introduction +[OpenBSD 7.6](https://openbsd.org/76.html) has ports for Radicale 1.x and 2.x but not for 3.x. Given the recent fairly active development of Radicale a port for Radicale 3.x would become outdated rapidly. As an alternative here are step-by-step instructions for installing Radicale 3.x on [OpenBSD 7.6](https://openbsd.org/76.html). + +## Limitations: +* These instructions only cover the [OpenBSD](https://openbsd.org) specific issues of installing Radicale itself. You may also want to set up TLS and/or a reverse proxy, authentication, etc. Please refer to the Radicale documentation, such as [https://radicale.org/v3.html](https://radicale.org/v3.html) or other parts of [this wiki](https://github.com/Kozea/Radicale/wiki), for these aspects of setting up the service. +* At the time of writing Radicale 3.3.0 was the latest version. Other versions are untested. +* Use at your own risk. + +# Prerequisites + +* A fresh installation of [OpenBSD 7.6](https://openbsd.org/76.html) is assumed. +* The [OpenBSD](https://openbsd.org) host needs to be able to access the Internet to install ports and to access the [pip](https://pypi.org/project/pip/) repository. +* Sufficient disk space to install [Python](https://python.org), the [virtual Python environment](https://docs.python.org/3/library/venv.html) and Radicale is assumed. (The needed space is not excessive, so in most cases this will be a non-issue.) +* You will need access as `root`, either directly or by using [doas(1)](https://man.openbsd.org/doas) on the host. These instructions assume direct `root` access as indicated by the `#` prompt. A `$` prompt indicates that no `root` access is required for the command. + +These instructions may also work on [OpenBSD 7.5](https://openbsd.org/75.html) and on future versions. But this is untested. + +# Installing Radicale + +1. Add the ports for [Python](https://python.org) and [pip](https://pypi.org/project/pip/) (unless they are already installed):\ +`# pkg_add python py3-pip` +2. Create a [virtual Python environment](https://docs.python.org/3/library/venv.html) to avoid mixing [pkg_add(1)](https://man.openbsd.org/pkg_add) and [pip](https://pypi.org/project/pip/) managed code:\ +`# python3 -m venv /usr/local/lib/radicale` +3. [Optional] Update [pip](https://pypi.org/project/pip/) in the [virtual Python environment](https://docs.python.org/3/library/venv.html) to silence warnings when using [pip](https://pypi.org/project/pip/):\ +`# /usr/local/lib/radicale/bin/pip install --upgrade pip` +4. Install Radicale into the [virtual Python environment](https://docs.python.org/3/library/venv.html):\ +`# /usr/local/lib/radicale/bin/pip install radicale` +5. Create a user and group for running Radicale:\ +`# useradd -g =uid -L daemon -c 'Radicale user' -s /sbin/nologin -u 672 -d /nonexistent _radicale`\ +Note: This is the same user and group that is installed by the Radicale 2.x port. If you feel that it is too dangerous to reuse the same name and UID/GID then feel free to use different values, but make sure you adjust the following instructions accordingly. +6. Create a directory for the Radicale configuration:\ +`# mkdir /etc/radicale` +7. Create at least a minimal configuration file `/etc/radicale/config` to override the default storage location `/var/lib/…` which doesn't exist on [OpenBSD](https://openbsd.org): +```ini +[storage] +filesystem_folder = /var/db/radicale/collections +``` +Of course you will probably want to add your own configuration settings to this file as well. + +8. Create the storage location and set its owner/group to the user/group created above:\ +`mkdir /var/db/radicale;chown _radicale:_radicale /var/db/radicale` +9. Create an [rc.d(8)](https://man.openbsd.org/rc.d) service script for Radicale as `/etc/rc.d/radicale3` and make it executable: +```sh +#!/bin/ksh + +daemon='/usr/local/lib/radicale/bin/radicale' +daemon_user='_radicale' +daemon_logger='daemon.info' + +. /etc/rc.d/rc.subr + +pexp=".* ${daemon}.*" +rc_reload=NO +rc_configtest=NO +rc_bg=YES + +rc_cmd $1 +``` +`# chmod 755 /etc/rc.d/radicale3` + +10. [Optional] Enable the service to start at system boot:\ +`# rcctl enable radicale3` +11. Start the Radicale service:\ +`# rcctl start radicale3` + +# Logging +Radicale Logs can be found in `/var/log/daemon`. You can configure [syslogd(8)](https://man.openbsd.org/syslogd) to place the logs into their own log file, e.g. by following these additional steps: + +12. Add the following to the top of `/etc/syslogd.conf`: +``` +!!radicale3 +daemon.info /var/log/radicale +!* +``` +13. Create the log file:\ +`# touch /var/log/radicale` +14. Reload the [syslogd(8)](https://man.openbsd.org/syslogd) configuration:\ +`# rcctl reload syslogd` +15. [Optional] Set up log rotation for the Radicale log file by adding something like the following to `/etc/newsyslog.conf`:\ +`/var/log/radicale 644 7 250 * Z` + +# Managing the service +FYI only (this is general [OpenBSD](https://openbsd.org) knowledge, not specific to Radicale). See [rcctl(8)](https://man.openbsd.org/rcctl) for details. + +## Stop the service +`# rcctl stop radicale3` + +## Check the service +`# rcctl check radicale3` + +`# rcctl ls started` + +## Restart the service/reload the configuration +`# rcctl restart radicale3` + +## Disable launching the service a system boot +`# rcctl disable radicale3` + + +# Updating Radicale +Once installed as described above there may come a time when you want to update Radicale to the newest version. + +1. Stop the Radicale service:\ +`# rcctl stop radicale3` +2. Update Radicale in the [virtual Python environment](https://docs.python.org/3/library/venv.html):\ +`# /usr/local/lib/radicale/bin/pip install --upgrade radicale` +3. Make any required changes to the configuration if the new version requires any changes. +4. Start the Radicale service:\ +`# rcctl start radicale3` + + +# Other + +Check which version of Radicale is installed:\ +`$ /usr/local/lib/radicale/bin/pip show radicale`