#title Amusewiki for system administrators #topics doc, howto #pubdate 2019-10-28 #lang en #teaser Essential things you have to know to manage Amusewiki on your servers 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. *** Location File produced by Amusewiki are located in =/var/lib/amusewiki=, including the sites repositories under =/var/lib/amusewiki/repo= You should backup this directory or mirror the repositories using git. If you want to setup a static site, serving =/var/lib/amusewiki/repo/site-code= as document root will do (just add an =index.html= pointing to =titles.html=). *** Services The process table for the user running =amusewiki= should look like this: {{{ # ps -u amusewiki -U amusewiki f PID TTY STAT TIME COMMAND 26702 ? Ss 0:02 perl-fcgi-pm 26722 ? S 18:16 \_ perl-fcgi 3268 ? S 16:49 \_ perl-fcgi 15818 ? S 15:33 \_ perl-fcgi 15980 ? S 15:19 \_ perl-fcgi 29350 ? S 5:43 \_ perl-fcgi 26698 ? Ss 1:18 /usr/bin/perl /usr/bin/amusewiki-jobber }}} 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: =amusewiki-web= and =amusewiki-jobber= so you can use standard systemd commands like =systemctl status= etc. here. There is also a 3rd process, =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. *** Logs **** Application By default, the application logs are left in =/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 =/var/lib/amusewiki/log4perl.conf= and explain what to do if you want to change that. This is how a =log4perl.local.conf= could look like: {{{ 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 }}} Further reading on this topic at [[https://metacpan.org/pod/Log::Log4perl]], but this is more a developer tool, so the default settings should be good enough. **** Nginx To get a grip on the load which the server is taking, you should look at the nginx logs located at =/var/log/nginx/*.log=. Each virtual host should have its own log. For Amusewiki, Nginx is controlled by 2 files: - =/etc/nginx/amusewikidebian_include= - =/etc/nginx/sites-enabled/amusewikidebian= 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 =amusewiki generate-nginx-conf= The master configuration file =/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. *** 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 =/var/lib/amusewiki/dbic.yaml= which contains the DSN and driver information. *** Utilities If you need to run some =Amusewiki= command, you should look at the =amusewiki= executable. {{{ 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 | stop | 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" }}} Please note that lately the =amusewiki restart= command fails to kill a process it spawns, so it needs to be killed manually (you are provided the target PID).