Created instructions for installing on OpenBSD 7.6

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`