\documentclass[DIV=13,%
BCOR=0mm,%
headinclude=false,%
footinclude=false,open=any,%
fontsize=10pt,%
oneside,%
paper=a5]%
{scrbook}
\usepackage[noautomatic]{imakeidx}
\usepackage{microtype}
\usepackage{graphicx}
\usepackage{alltt}
\usepackage{verbatim}
\usepackage[shortlabels]{enumitem}
\usepackage{tabularx}
\usepackage[normalem]{ulem}
\def\hsout{\bgroup \ULdepth=-.55ex \ULset}
% https://tex.stackexchange.com/questions/22410/strikethrough-in-section-title
% Unclear if \protect \hsout is needed. Doesn't looks so
\DeclareRobustCommand{\sout}[1]{\texorpdfstring{\hsout{#1}}{#1}}
\usepackage{wrapfig}
% avoid breakage on multiple
and avoid the next [] to be eaten
\newcommand*{\forcelinebreak}{\strut\\*{}}
\newcommand*{\hairline}{%
\bigskip%
\noindent \hrulefill%
\bigskip%
}
% reverse indentation for biblio and play
\newenvironment*{amusebiblio}{
\leftskip=\parindent
\parindent=-\parindent
\smallskip
\indent
}{\smallskip}
\newenvironment*{amuseplay}{
\leftskip=\parindent
\parindent=-\parindent
\smallskip
\indent
}{\smallskip}
\newcommand*{\Slash}{\slash\hspace{0pt}}
% http://tex.stackexchange.com/questions/3033/forcing-linebreaks-in-url
\PassOptionsToPackage{hyphens}{url}\usepackage[hyperfootnotes=false,hidelinks,breaklinks=true]{hyperref}
\usepackage{bookmark}
\usepackage{fontspec}
\usepackage{polyglossia}
\setmainlanguage{english}
\setmainfont{texgyrepagella-regular.otf}[Script=Latin,%
Ligatures=TeX,%
Path=/usr/share/texmf/fonts/opentype/public/tex-gyre/,%
BoldFont=texgyrepagella-bold.otf,%
BoldItalicFont=texgyrepagella-bolditalic.otf,%
ItalicFont=texgyrepagella-italic.otf]
\setmonofont{cmuntt.ttf}[Script=Latin,%
Ligatures=TeX,%
Scale=MatchLowercase,%
Path=/usr/share/fonts/truetype/cmu/,%
BoldFont=cmuntb.ttf,%
BoldItalicFont=cmuntx.ttf,%
ItalicFont=cmunit.ttf]
\setsansfont{cmunss.ttf}[Script=Latin,%
Ligatures=TeX,%
Scale=MatchLowercase,%
Path=/usr/share/fonts/truetype/cmu/,%
BoldFont=cmunsx.ttf,%
BoldItalicFont=cmunso.ttf,%
ItalicFont=cmunsi.ttf]
\newfontfamily\englishfont{texgyrepagella-regular.otf}[Script=Latin,%
Ligatures=TeX,%
Path=/usr/share/texmf/fonts/opentype/public/tex-gyre/,%
BoldFont=texgyrepagella-bold.otf,%
BoldItalicFont=texgyrepagella-bolditalic.otf,%
ItalicFont=texgyrepagella-italic.otf]
\renewcommand*{\partpagestyle}{empty}
% global style
\pagestyle{plain}
\usepackage{indentfirst}
% remove the numbering
\setcounter{secnumdepth}{-2}
% remove labels from the captions
\renewcommand*{\captionformat}{}
\renewcommand*{\figureformat}{}
\renewcommand*{\tableformat}{}
\KOMAoption{captions}{belowfigure,nooneline}
\addtokomafont{caption}{\centering}
\deffootnote[3em]{0em}{4em}{\textsuperscript{\thefootnotemark}~}
\addtokomafont{disposition}{\rmfamily}
\addtokomafont{descriptionlabel}{\rmfamily}
\frenchspacing
% avoid vertical glue
\raggedbottom
% this will generate overfull boxes, so we need to set a tolerance
% \pretolerance=1000
% pretolerance is what is accepted for a paragraph without
% hyphenation, so it makes sense to be strict here and let the user
% accept tweak the tolerance instead.
\tolerance=200
% Additional tolerance for bad paragraphs only
\setlength{\emergencystretch}{30pt}
% (try to) forbid widows/orphans
\clubpenalty=10000
\widowpenalty=10000
% given that we said footinclude=false, this should be safe
\setlength{\footskip}{2\baselineskip}
\title{Amusewiki for system administrators}
\date{}
\author{}
\subtitle{}
% https://groups.google.com/d/topic/comp.text.tex/6fYmcVMbSbQ/discussion
\hypersetup{%
pdfencoding=auto,
pdftitle={Amusewiki for system administrators},%
pdfauthor={},%
pdfsubject={},%
pdfkeywords={doc; howto}%
}
\begin{document}
\begin{titlepage}
\strut\vskip 2em
\begin{center}
{\usekomafont{title}{\huge Amusewiki for system administrators\par}}%
\vskip 1em
\vskip 2em
\vskip 1.5em
\vfill
\strut\par
\end{center}
\end{titlepage}
\cleardoublepage
\tableofcontents
% start a new right-handed page
\cleardoublepage
This guide assumes you installed Amusewiki with the recommended Debian
packages, which gives a standard and recommended setup, providing a
more straightforward debugging if the need arises. If you have it
installed from source, reading this should still be worth of it.
\section{Location}
File produced by Amusewiki are located in \texttt{/var/lib/amusewiki},
including the sites repositories under \texttt{/var/lib/amusewiki/repo}
You should backup this directory or mirror the repositories using git.
If you want to setup a static site, serving
\texttt{/var/lib/amusewiki/repo/site-code} as document root will do (just add
an \texttt{index.html} pointing to \texttt{titles.html}).
\section{Services}
The process table for the user running \texttt{amusewiki} should look like this:
\begin{alltt}
\# ps -u amusewiki -U amusewiki f
PID TTY STAT TIME COMMAND
26702 ? Ss 0:02 perl-fcgi-pm
26722 ? S 18:16 \textbackslash{}\_ perl-fcgi
3268 ? S 16:49 \textbackslash{}\_ perl-fcgi
15818 ? S 15:33 \textbackslash{}\_ perl-fcgi
15980 ? S 15:19 \textbackslash{}\_ perl-fcgi
29350 ? S 5:43 \textbackslash{}\_ perl-fcgi
26698 ? Ss 1:18 /usr/bin/perl /usr/bin/amusewiki-jobber
\end{alltt}
The first process (in this example with PID 26702) is the FCGI process
manager, while its children are the workers for the application
itself. The web pages are served via Nginx as reverse proxy.
The last process (in this example with PID 26698) is the background
daemon in charge for the publishing, indexing, PDF compilation. When
active, you will see it spawning forks, while when not under load you
should see just one of it.
These two services can operate independently and are controlled by two
systemd unit: \texttt{amusewiki-web} and \texttt{amusewiki-jobber} so you can use
standard systemd commands like \texttt{systemctl status} etc. here.
There is also a 3rd process, \texttt{amusewiki-cgit}, which is in charge to
run cgit on localhost (which Amusewiki serves when you look at the
history of a page). You are not supposed to have much to do with this
service. When Amusewiki is installed from source, this service may or
may be not be present, it could be Nginx directly serving that.
\section{Logs}
\subsection{Application}
By default, the application logs are left in
\texttt{/var/lib/amusewiki/log/amw-2019-10-28.log} with the timestamp on the
filename (so each day is a new log). Errors are instead mailed
directly to root@localhost.
The configuration file for the logging is
\texttt{/var/lib/amusewiki/log4perl.conf} and explain what to do if you want
to change that.
This is how a \texttt{log4perl.local.conf} could look like:
\begin{alltt}
log4perl.logger=INFO,Log
log4perl.logger.main=INFO
\# debug individual modules
log4perl.logger.AmuseWikiFarm.Controller.Edit=DEBUG
log4perl.logger.AmuseWikiFarm.Schema.Result.Revision=DEBUG
\# define the "Log" logger
log4perl.appender.Log=Log::Dispatch::File::Stamped
log4perl.appender.Log.filename=log/amw.log
log4perl.appender.Log.stamp\_fmt=\%Y-\%m-\%d
log4perl.appender.Log.mode=append
log4perl.appender.Log.layout=Log::Log4perl::Layout::PatternLayout
log4perl.appender.Log.layout.ConversionPattern=\%d \%p - \%c - \%F:\%L - \%m\%n
\end{alltt}
Further reading on this topic at
\href{https://metacpan.org/pod/Log::Log4perl}{\texttt{https://metacpan.org/pod/Log::Log4perl}}, but this is more a
developer tool, so the default settings should be good enough.
\subsection{Nginx}
To get a grip on the load which the server is taking, you should look
at the nginx logs located at \texttt{/var/log/nginx/*.log}. Each virtual host
should have its own log.
For Amusewiki, Nginx is controlled by 2 files:
\begin{itemize}
\item\relax
\texttt{/etc/nginx/amusewikidebian\_include}
\item\relax
\texttt{/etc/nginx/sites-enabled/amusewikidebian}
\end{itemize}
They are usually autogenerated by the application, you are usually
prompted to run the needed commands as root when e.g. installing new
sites.
The same happens when calling \texttt{amusewiki generate-nginx-conf}
The master configuration file \texttt{/etc/nginx/nginx.conf} is your sole
responsibility so Amusewiki never touches it. If you need to adjust
logging format or global settings, this is usually the place.
\section{Database}
Amusewiki can work with MySQL, PostgreSQL and SQLite (not recommended
for production). DB installation is managed by the Debian package and
should work out of the box. To find out what you are using the
configuration file is \texttt{/var/lib/amusewiki/dbic.yaml} which contains
the DSN and driver information.
\section{Utilities}
If you need to run some \texttt{Amusewiki} command, you should look at the
\texttt{amusewiki} executable.
\begin{alltt}
Usage: amusewiki action [ argument1, argument2]
Run the amusewiki scripts as user amusewiki in the correct directory.
Available commands:
amusewiki bootstrap-archive
amusewiki check-compiler
amusewiki clone-site
amusewiki create-doc-site
amusewiki export-titles
amusewiki generate-meta-config
amusewiki generate-nginx-conf
amusewiki import-redirections
amusewiki jobber
amusewiki letsencrypt
amusewiki populate-monthly
amusewiki populate-webfonts
amusewiki reset-password
amusewiki set-site-variable
amusewiki upgrade-db
amusewiki upgrade-lexicon
amusewiki shell
The shell subcommand will start a shell with the amusewiki user
See man amusewiki- for usage of each command
or run amusewiki --help
Other useful commands:
amusewiki [ start \textbar{} stop \textbar{} restart ]
start and stop actions simply call systemctl, while the restart action
performs a restart without downtime (so being a bit more useful than
just "systemctl restart amusewiki-web amusewiki-jobber amusewiki-cgit"
\end{alltt}
Please note that lately the \texttt{amusewiki restart} command fails to kill
a process it spawns, so it needs to be killed manually (you are
provided the target PID).
% begin final page
\clearpage
% new page for the colophon
\thispagestyle{empty}
\begin{center}
\bigskip
\includegraphics[width=0.25\textwidth]{logo-amw.pdf}
\bigskip
\end{center}
\strut
\vfill
\begin{center}
Amusewiki for system administrators
\bigskip
\bigskip
\textbf{amusewiki.org}
\end{center}
% end final page with colophon
\end{document}
% No format ID passed.