aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorWojtek Kosior <koszko@koszko.org>2022-04-27 12:08:25 +0200
committerWojtek Kosior <koszko@koszko.org>2022-04-27 12:08:25 +0200
commitae96024993f111bcb1e48824f5f63be63ef38b1f (patch)
treecaa5f87385a97b1e94aab12318caa6fc0bf6d8a6 /doc
parent376425d547b12f0e09c7c9636ad891a3ede0e272 (diff)
downloadhaketilo-hydrilla-ae96024993f111bcb1e48824f5f63be63ef38b1f.tar.gz
haketilo-hydrilla-ae96024993f111bcb1e48824f5f63be63ef38b1f.zip
New upstream version 1.0upstream/1.0
Diffstat (limited to 'doc')
-rw-r--r--doc/examples/hydrilla.example.com.conf77
-rw-r--r--doc/examples/hydrilla.example.com.tls.conf94
-rw-r--r--doc/examples/hydrilla.wsgi27
-rw-r--r--doc/man/man1/hydrilla.1137
4 files changed, 335 insertions, 0 deletions
diff --git a/doc/examples/hydrilla.example.com.conf b/doc/examples/hydrilla.example.com.conf
new file mode 100644
index 0000000..c1450f1
--- /dev/null
+++ b/doc/examples/hydrilla.example.com.conf
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: CC0-1.0
+
+# Sample Apache2 configuration file for Hydrilla server (over unencrypted HTTP).
+#
+# Copyright (C) 2022 Wojtek Kosior
+
+
+# Please adapt this file according to your needs can place it file under
+# Apache2's available site configs directory which will be
+# /etc/apache2/sites-available/ or similar. Then, enable it using the following
+# command:
+# a2ensite hydrilla.example.com
+# You also need to install and enable the wsgi module for Apache if you haven't
+# already (e.g. with libapache2-mod-wsgi-py3 Debian package).
+# The new configuration will only take effect after you restart/reload Apache2
+# daemon.
+
+# Keep in mind that due to some external limitations Haketilo will not connect
+# to HTTP Hydrilla servers running elsewhere than localhost. To get a working
+# public Hydrilla server you should obtain a TLS certificate and use the
+# attached hydrilla.example.com.tls.conf file instead of this one.
+
+# This configuration file assumes Hydrilla is installed under Python's default
+# load path and that the attached hydrilla.wsgi sample script has been saved as
+# /var/lib/hydrilla/wsgi/hydrilla.wsgi
+
+<VirtualHost *:80>
+ ServerName hydrilla.example.com
+ ServerAdmin admin@example.com
+
+ DocumentRoot /var/lib/hydrilla/malcontent
+
+ <Directory /var/lib/hydrilla/malcontent >
+ <IfVersion < 2.4>
+ Order allow,deny
+ Allow from all
+ </IfVersion>
+ <IfVersion >= 2.4>
+ Require all granted
+ </IfVersion>
+ </Directory>
+
+ <Directory ~ "^/var/lib/hydrilla/malcontent/(resource|mapping)/" >
+ ForceType application/json
+ </Directory>
+
+ # Make Apache2 automatically pick up the new version of the wsgi script when
+ # it gets written. This line will fail if you don't have mod_wsgi installed
+ # and enabled.
+ WSGIScriptReloading On
+
+ # The default configuration of mod_wsgi on most *nix systems is to run wsgi
+ # scripts in so-called embedded mode. The following 2 lines instruct Apache to
+ # instead run our wsgi script in a daemon process which makes it more flexible
+ # and reliable. Here we also set environment variables that are needed to tell
+ # Python that the system supports UTF-8 encoding.
+ # Feel free to modify the arguments to WSGIDaemonProcess according to your
+ # needs:
+ # https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html#delegation-to-daemon-process
+ WSGIDaemonProcess hydrilla.example.com lang='C.UTF-8' locale='C.UTF-8'
+ WSGIProcessGroup hydrilla.example.com
+
+ <Directory /var/lib/hydrilla/wsgi >
+ <IfVersion < 2.4>
+ Order allow,deny
+ Allow from all
+ </IfVersion>
+ <IfVersion >= 2.4>
+ Require all granted
+ </IfVersion>
+ </Directory>
+
+ WSGIScriptAliasMatch "^/((resource|mapping)/[^/]+[.]json|query)$" "/var/lib/hydrilla/wsgi/hydrilla.wsgi/$1"
+
+ ErrorLog ${APACHE_LOG_DIR}/error.log
+ CustomLog ${APACHE_LOG_DIR}/access.log combined
+</VirtualHost>
diff --git a/doc/examples/hydrilla.example.com.tls.conf b/doc/examples/hydrilla.example.com.tls.conf
new file mode 100644
index 0000000..357ecb3
--- /dev/null
+++ b/doc/examples/hydrilla.example.com.tls.conf
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: CC0-1.0
+
+# Sample Apache2 configuration file for Hydrilla server (over HTTPS).
+#
+# Copyright (C) 2022 Wojtek Kosior
+
+
+# Please adapt this file according to your needs can place it file under
+# Apache2's available site configs directory which will be
+# /etc/apache2/sites-available/ or similar. Then, enable it using the following
+# command:
+# a2ensite hydrilla.example.com.tls
+# You also need to install and enable the wsgi module for Apache if you haven't
+# already (e.g. with libapache2-mod-wsgi-py3 Debian package).
+# The new configuration will only take effect after you restart/reload Apache2
+# daemon.
+
+# The following configuration enables TLS encryption. If you want to run a local
+# Hydrilla server utilizing plain HTTP, use the attached
+# hydrilla.example.com.conf file instead of this one or run a standalone
+# development server using the hydrilla command.
+
+# This configuration file assumes Hydrilla is installed under Python's default
+# load path and that the attached hydrilla.wsgi sample script has been saved as
+# /var/lib/hydrilla/wsgi/hydrilla.wsgi
+
+<VirtualHost *:80>
+ ServerName hydrilla.example.com
+
+ Redirect permanent / https://hydrilla.example.com/
+
+ ErrorLog ${APACHE_LOG_DIR}/error.log
+ CustomLog ${APACHE_LOG_DIR}/access.log combined
+</VirtualHost>
+
+<IfModule mod_ssl.c>
+ <VirtualHost _default_:443>
+ ServerName hydrilla.example.com
+ ServerAdmin admin@example.com
+
+ DocumentRoot /var/lib/hydrilla/malcontent
+
+ <Directory /var/lib/hydrilla/malcontent >
+ <IfVersion < 2.4>
+ Order allow,deny
+ Allow from all
+ </IfVersion>
+ <IfVersion >= 2.4>
+ Require all granted
+ </IfVersion>
+ </Directory>
+
+ <Directory ~ "^/var/lib/hydrilla/malcontent/(resource|mapping)/" >
+ ForceType application/json
+ </Directory>
+
+ # Make Apache2 automatically pick up the new version of the wsgi script when
+ # it gets written. This line will fail if you don't have mod_wsgi installed
+ # and enabled.
+ WSGIScriptReloading On
+
+ # The default configuration of mod_wsgi on most *nix systems is to run wsgi
+ # scripts in so-called embedded mode. The following 2 lines instruct Apache
+ # to instead run our wsgi script in a daemon process which makes it more
+ # flexible and reliable. Here we also set environment variables that are
+ # needed to tell Python that the system supports UTF-8 encoding.
+ # Feel free to modify the arguments to WSGIDaemonProcess according to your
+ # needs:
+ # https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html#delegation-to-daemon-process
+ WSGIDaemonProcess hydrilla.example.com lang='C.UTF-8' locale='C.UTF-8'
+ WSGIProcessGroup hydrilla.example.com
+
+ <Directory /var/lib/hydrilla/wsgi >
+ <IfVersion < 2.4>
+ Order allow,deny
+ Allow from all
+ </IfVersion>
+ <IfVersion >= 2.4>
+ Require all granted
+ </IfVersion>
+ </Directory>
+
+ WSGIScriptAliasMatch "^/((resource|mapping)/[^/]+[.]json|query)$" "/var/lib/hydrilla/wsgi/hydrilla.wsgi/$1"
+
+ ErrorLog ${APACHE_LOG_DIR}/error.log
+ CustomLog ${APACHE_LOG_DIR}/access.log combined
+
+ # Change the paths to point to your actual certificate files.
+ SSLEngine on
+ SSLCertificateFile /etc/letsencrypt/live/example.com/cert.pem
+ SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
+ SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
+ </VirtualHost>
+</IfModule>
diff --git a/doc/examples/hydrilla.wsgi b/doc/examples/hydrilla.wsgi
new file mode 100644
index 0000000..70dd895
--- /dev/null
+++ b/doc/examples/hydrilla.wsgi
@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+
+# SPDX-License-Identifier: CC0-1.0
+
+# Sample WSGI script for Hydrilla server.
+#
+# Copyright (C) 2022 Wojtek Kosior
+
+# Uncomment the lines below if you want to use a virtualenv installation of
+# Hydrilla.
+
+#from pathlib import Path
+#path = Path('/path/to/virtualenv/bin/activate_this.py')
+#exec(path.read_text(), {'__file__': str(path)})
+
+from hydrilla.server import start_wsgi
+
+# The following line will initialize Hydrilla with the default, internal
+# configuration while also attempting to load /etc/hydrilla/config.json if it's
+# present.
+application = start_wsgi(standalone_mode=False)
+
+# Comment the above and uncomment this to use a different config file.
+
+#from hydrilla.server import config
+#application = start_wsgi(standalone_mode=False,
+# obj=config.load(['/path/to/config.json']))
diff --git a/doc/man/man1/hydrilla.1 b/doc/man/man1/hydrilla.1
new file mode 100644
index 0000000..c71428c
--- /dev/null
+++ b/doc/man/man1/hydrilla.1
@@ -0,0 +1,137 @@
+.\" SPDX-License-Identifier: CC0-1.0
+.\"
+.\" Man page for Hydrilla server.
+.\"
+.\" Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
+.\"
+.\" Available under the terms of Creative Commons Zero v1.0 Universal.
+
+.TH HYDRILLA 1 2022-04-22 "Hydrilla 1.0" "Hydrilla Manual"
+
+.SH NAME
+hydrilla \- Serve packages for the Haketilo browser extension
+
+.SH SYNOPSIS
+.B "hydrilla \-\-help"
+.br
+.B "hydrilla [\-m \fIDIRECTORY\/\fP] [\-h\ \fIURL\/\fP]"
+.B "[\-p\ \fIPORT\/\fP] [\-l \fILANGUAGE\/\fP]"
+.br
+.B " [\-c \fICONFIG\/\fP]"
+.br
+(See the OPTIONS section for alternate option syntax with long option
+names.)
+
+.SH DESCRIPTION
+.I hydrilla
+is a command to start the Hydrilla repository software that serves Haketilo
+packages over HTTP.
+
+The primary method of running Hydrilla server is through a WSGI script.
+.I hydrilla
+command should only be used in local or development deployments.
+
+.SH OPTIONS
+.TP
+.B \-\^\-help
+Output a usage message and exit.
+
+.TP
+.BI \-m " DIRECTORY" "\fR,\fP \-\^\-malcontent\-dir=" DIRECTORY
+Look inside
+.I DIRECTORY
+for package files to serve. Use of the word \*(lqmalcontent\*(rq is a
+pun on widespread use of word
+.UR https://www.gnu.org/philosophy/words-to-avoid.en.html#Content
+\*(lqcontent\*(rq
+.UE
+with regard to works published online.
+
+This option, if present, overrides the property \*(lqmalcontent_dir\*(rq from Hydrilla config file. If the value is not specified on the command line nor in the config file, it defaults to \%\*(lq/var/lib/hydrilla/malcontent\*(rq.
+
+.TP
+.BI \-h " URL" "\fR,\fP \-\^\-hydrilla\-project\-url=" URL
+Use
+.I URL
+when placing a link to Hydrilla website in served HTML pages.
+
+This option, if present, overrides the property \*(lqhydrilla_project_url\*(rq from Hydrilla config file. If the value is not specified on the command line nor in the config file, it defaults to \%\*(lqhttps://hydrillabugs.koszko.org/projects/hydrilla/wiki\*(rq.
+
+.TP
+.BI \-p " PORT" "\fR,\fP \-\^\-port=" PORT
+Run the Hydrilla HTTP server on port
+.IR PORT .
+If
+.I PORT
+is 0, let
+.I hydrilla
+choose a random free port on the machine.
+
+This option, if present, overrides the property \*(lqport\*(rq from Hydrilla config file. If the value is not specified on the command line nor in the config file, it defaults to 10112.
+
+.TP
+.BI \-l " LANGUAGE" "\fR,\fP \-\^\-language=" LANGUAGE
+Generate all user messages (including those on served HTML pages) using
+locale
+.IR LANGUAGE .
+
+.I LANGUAGE
+should be one of the locales supported by
+.IR hydrilla ,
+e.g. \*(lqen_US\*(rq.
+Otherwise,
+.I hydrilla
+will silently fall back to the en_US locale.
+
+This option, if present, overrides the property \*(lqlanguage\*(rq from Hydrilla config file. If the value is not specified on the command line nor in the config file, it defaults to \*(lqen_US\*(rq.
+
+.TP
+.BI \-c " CONFIG" "\fR,\fP \-\^\-config=" CONFIG
+Process the file at
+.I CONFIG
+as Hydrilla config file.
+.I CONFIG
+must exist in the filesystem and be readable to
+.IR hydrilla .
+
+If this option is not given,
+.I hydrilla
+loads its own, internal config file that in turn tries to load
+\%/etc/hydrilla/config.json.
+
+.TP
+.B \-\^\-version
+Show version information for this instance of
+.I hydrilla
+on the standard output and exit successfully.
+
+.SH "EXIT STATUS"
+The exit status is 0 if the server was started successfully and terminated
+manually by the user (i.e. through delivery of a SIGINT signal) or if the
+.B \-\^\-help
+option was passed. It is a number different from 0 if the server failed to
+start.
+Possible causes include
+.\"
+invalid command line arguments,
+.\"
+broken packages inside the provided
+.I DIRECTORY
+(may instead generate a warning message depending on the \*(lqwerror\*(rq
+config file option),
+.\"
+insufficient privileges to use the specified
+.I PORT
+and
+.\"
+invalid or unreadable config file.
+
+.SH "SEE ALSO"
+.SS "Manual Pages"
+.BR hydrilla-builder (1).
+
+.SS "Full Documentation"
+.UR https://hydrillabugs.koszko.org/projects/hydrilla/wiki
+Online documentation
+.UE
+is available on Hydrilla issue tracker.