Marco Pessotto
How to install AmuseWiki
The recommended way to install amusewiki is via http://packages.amusewiki.org, where a debian repository with the packages is provided. If you want to install manually, read on, otherwise skip this document.
The installation of amusewiki takes time (depending on speed of the machine and of the network) and requires about 5Gb of disk space because of the full installation of TeXlive. If you're short on disk space, don't even start to install (the app will create files at full speed anyway, so consider 10Gb for a reasonable start).
On a slow server, it takes 2 hours (mostly spent on installing and testing Perl modules, and 20 minutes to download and install the full TeXlive 2015), but the procedure is fully automated, so start it, check if it bails out at the beginning, forget about it for an hour or two (run it under screen), then come back later and finish it up to complete it for the operations which require root privileges (notably the webserver configuration).
You can speed up the process installing the available modules and texlive from the OS repositories, which is the suggested approch because this way the security fixes are delegated to the standard tools.
The supported and recommended setup is nginx + FCGI. The FCGI setup should work with Apache as well, but it's not currently actively supported, even if perldoc Catalyst::Manual::Deployment::Apache::FastCGI should help.
Prerequisites:
-
a database (mysql, pg, sqlite are supported)
-
a working perl (i.e., you can install modules with cpanm without warnings). Usually this means you have to install liblocal-lib-perl and cpanminus in Debian (or you install perl in your home).
-
fontconfig (install it before installing texlive)
-
graphicsmagick (for thumbnails) and imagemagick (for preview generation)
-
a mime-info database: shared-mime-info on debian
-
a dedicated system user (with a clean home) which is going to run the site
-
SSL binaries and development libraries (openssl and libssl-dev)
-
Xapian libraries and development files (xapian-tools libxapian-dev)
-
commonly used utilities: unzip, wget, git, rsync
-
TeXlive full > 2012, either from system repo (recommended) or from https://www.tug.org/texlive/
Log in as the user you want to run the site.
If you have a system wide perl, to install modules in your home you should install local::lib (liblocal-lib-perl on Debian) and add to .profile (or equivalent):
eval `perl -Mlocal::lib`
If you installed Tex live from the installer, tweak the shell rc file to include the binaries in the PATH.
Logout and login again.
Unpack the sources (or clone the repo) and change directory into them.
Install the prerequisites and complete the installation with:
Complete the installation with:
./script/install.sh
Configure the initial site
Create a database for the application. E.g., for mysql:
mysql> create database amuse DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; mysql> grant all privileges on amuse.* to amuse@localhost identified by XXX
Or, for postgres:
Login as root.
su - postgres psql create user amuse with password 'XXXX'; create database amuse owner amuse;
For sqlite no setup is required.
Copy dbic.yaml.<dbtype>.example to dbic.yaml and adjust the credentials, and chmod it to 600. (For sqlite is good as it is).
If you have multiple amusewiki instance (please note, multiple sites are just fine on a single instance) on the same machine, see below before proceeding (you probably want to tweak the configuration)
Configure the initial site with:
./script/configure.sh [ hostname ]
Please note that the installation procedure will create a mirror of amusewiki.org under the subdomain amusewiki.<your domain>, where <your domain> is the output of `hostname -d`. Nothing you can't change later from the admin console, but you need to access it. You can pass the desired hostname as first argument to the configure script.
Start the application
To set the number of FCGI workers, set the environment variable AMW_WORKERS (defaults to 3).
export AMW_WORKERS=5
To start/stop/restart the application:
./init-all start ./init-all stop ./init-all restart
This is not needed if you use systemd.
To regenerate the nginx configuration after adding a site:
./script/amusewiki-generate-nginx-conf
(and read the output).
Multiple installations
If you run a Debian machine and you have only one instance running and if you have the port 9015 free, you don't need any of this.
Please note: "multiple instances" doesn't mean "multiple sites". On a single instance you can have as many sites as you want.
The interaction between nginx and the application, including cgit, is controlled by the Webserver model. You can configure it creating a file in the application root named amusewikifarm_local.conf with this content (here listed with the defaults).
<Model::Webserver>
# cgit port
cgit_port 9015
log_format combined
nginx_root /etc/nginx
instance_name amusewiki
fcgiwrap_socket /var/run/fcgiwrap.socket
</Model::Webserver>
The instance_name is just a string used to create the nginx configuration files to avoid conflicts with other installations. So you may have one instance named "testing" and the other "live".
FreeBSD
Install as much as possible from the repository:
pkg install perl5 p5-App-cpanminus git texlive-full-20150521 \
cgit ImageMagick \
GraphicsMagick shared-mime-info xapian-core xapian-bindings \
nginx fcgiwrap unzip rsync wget bash \
p5-Module-Install \
p5-local-lib \
p5-Catalyst-Devel \
p5-DBIx-Class p5-DBIx-Class-Schema-Loader p5-DBIx-Class-PassphraseColumn \
p5-DBIx-Class-DeploymentHandler p5-DBIx-Class-Helpers p5-DBIx-Class-Schema-Config \
p5-DateTime-Format-RFC3339 \
p5-Locale-Maketext-Lexicon \
p5-Locale-PO p5-File-MimeInfo \
p5-Protocol-ACME \
p5-CAM-PDF \
p5-Test-Differences \
p5-Catalyst-Runtime \
p5-Catalyst-Plugin-ConfigLoader \
p5-Catalyst-Plugin-Authentication \
p5-Catalyst-Plugin-Session \
p5-Catalyst-Plugin-Session-Store-FastMmap \
p5-Catalyst-Plugin-Session-State-Cookie \
p5-Catalyst-Plugin-Authorization-Roles \
p5-Catalyst-View-TT \
p5-Catalyst-Action-RenderView \
p5-Moose \
p5-namespace-autoclean \
p5-Test-WWW-Mechanize-Catalyst \
p5-Term-Size-Any \
p5-MIME-Types \
p5-FCGI \
p5-FCGI-ProcManager \
p5-Unicode-Collate \
p5-DBIx-Class \
p5-DBD-SQLite \
p5-Daemon-Control \
p5-MooseX-NonMoose \
p5-JSON \
p5-JSON-XS \
p5-DBIx-Class-Schema-Loader \
p5-SQL-Translator \
p5-DBIx-Class-Schema-Config \
p5-DBIx-Class-PassphraseColumn \
p5-DBIx-Class-InflateColumn-Authen-Passphrase \
p5-DateTime \
p5-DateTime-Format-SQLite \
p5-DateTime-Format-MySQL \
p5-DateTime-Format-Pg \
p5-DateTime-Format-Strptime \
p5-XML-FeedPP \
p5-XML-Atom \
p5-Git-Wrapper \
p5-Text-Wrapper \
p5-Email-Valid \
p5-File-Copy-Recursive \
p5-Search-Xapian \
p5-Catalyst-Model-Adaptor \
p5-Text-Unidecode \
p5-Log-Contextual \
p5-Log-Log4perl \
p5-Log-Dispatch \
p5-Log-Dispatch-File-Stamped \
p5-Email-Sender \
p5-HTTP-Tiny \
p5-MooseX-MarkAsMethods \
p5-PDF-API2 \
p5-Bytes-Random-Secure \
p5-Crypt-OpenSSL-X509 \
p5-HTTP-BrowserDetect \
p5-Type-Tiny \
p5-Archive-Zip \
p5-Template-Tiny \
p5-Catalyst-Model-DBIC-Schema
[root@freebsd ~]# adduser Username: amusewiki Full name: Amusewiki Uid (Leave empty for default): Login group [amusewiki]: Login group is amusewiki. Invite amusewiki into other groups? []: Login class [default]: Shell (sh csh tcsh zsh rzsh bash rbash git-shell nologin) [sh]: bash Home directory [/home/amusewiki]: Home directory permissions (Leave empty for default): Use password-based authentication? [yes]: no Lock out the account after creation? [no]: Username : amusewiki Password : <disabled> Full Name : Amusewiki Uid : 1001 Class : Groups : amusewiki Home : /home/amusewiki Home Mode : Shell : /usr/local/bin/bash Locked : no OK? (yes/no): yes adduser: INFO: Successfully added (amusewiki) to the user database. Add another user? (yes/no): no Goodbye!
Add to rc.conf
nginx_enable=YES
fcgiwrap_enable=YES
fcgiwrap_user=www
fcgiwrap_socket="unix:/var/run/fcgiwrap/socket"
# create an include sites-enabled directory for nginx and log dir
mkdir /usr/local/etc/nginx/sites-enabled
mkdir /var/log/nginx/
# and add an include directive in nginx.conf inside the http { } stanza, at the end.
# include /usr/local/etc/nginx/sites-enabled/*;
vi /usr/local/etc/nginx/nginx.conf
And start the services
service nginx start service fcgiwrap start
su - amusewiki
git clone https://github.com/melmothx/amusewiki.git
cd amusewiki
eval `perl -Mlocal::lib`
./script/install.sh
# create the config
cat << EOF > amusewikifarm_local.conf
<Model::Webserver>
nginx_root /usr/local/etc/nginx
fcgiwrap_socket /var/run/fcgiwrap/socket
</Model::Webserver>
EOF
Then decide to which hostname you want to serve this and run
./script/configure.sh amw.localdomain
Take note of the credentials, and follow the instructions.
CentOS 7
Most of these instructions will apply to other GNU/Linux systems with systemd and selinux.
Texlive is obsolete, so we will install it from CTAN. The same goes with perl.
From a fresh install:
# yum install epel-release
# yum install git nginx perl-local-lib sqlite cgit \
perl-App-cpanminus fontconfig GraphicsMagick ImageMagick shared-mime-info openssl openssl-devel \
xapian-core xapian-core-devel unzip wget libxml2 libxml2-devel expat-devel \
policycoreutils setroubleshoot
# yum groupinstall 'Development Tools'
Tweak nginx configuration to conform to debian standard
# mkdir /etc/nginx/sites-enabled
Modify /etc/nginx/nginx.conf adding this line:
include /etc/nginx/sites-enabled/*;
Right after include /etc/nginx/conf.d/*.conf;
(Probably you may also want to add client_max_body_size 8m; as the
default is way too low).
Start nginx:
# systemctl enable nginx # systemctl start nginx
Open the firewall
# firewall-cmd --get-active-zones # firewall-cmd --zone=public --add-service=http --permanent # firewall-cmd --zone=public --add-service=https --permanent # firewall-cmd --reload
Prepare the installation directory for your user (say amusewiki, but any other will do).
Please note that we install it under /var/www/ to avoid problems
with SELinux.
# mkdir /var/www/amusewiki # chown amusewiki:amusewiki /var/www/amusewiki
As the user which is going to run amusewiki, install a fresh perl. This way we simplify and make our install independent from the base system, which is lacking way too many modules.
$ eval `perl -Mlocal::lib` $ cpanm Perl::Build $ perl-build -j 3 --test 5.24.1 $HOME/amw-perl $ cd /vaw/www/amusewiki $ git clone https://github.com/melmothx/amusewiki.git $ cd amusewiki # you're now in /vaw/www/amusewiki/amusewiki, our app home $ ./script/install-texlive.sh # install texlive $ echo 'export PATH=$HOME/amw-perl/bin:$HOME/texlive/2017/bin/x86_64-linux:$PATH' >> $HOME/.bashrc $ chmod 755 $HOME # open the home so plackup is accessible to nginx
Logout and login again and check the program paths to point to the newly installed ones
$ which perl # should be: ~/amw-perl/bin/perl $ which xelatex # should be ~/texlive/2017/bin/x86_64-linux/xelatex
Install cpanm and the dependencies
$ perl -MCPAN -e 'install App::cpanminus' $ which cpanm # should be ~/amw-perl/bin/cpanm $ cd /var/www/amusewiki/amusewiki/ $ ./script/install.sh
Decide the initial server name to serve amusewiki (to get access to the admin), e.g. amw.localdomain.
See above if you want a mysql or postgresql database. The following command will create a sample site with the current amusewiki documentation.
$ ./script/configure.sh amw.localdomain
Remove the cgit wrapper, we're going to install systemd unit files.
$ rm root/git/cgit.cgi $ ./script/generate-systemd-unit-files $ ./script/amusewiki-generate-nginx-conf
Read the output and install the fresh nginx configuration.
Finally, open the permission for selinux. As root:
cd /var/www/amusewiki/amusewiki/doc/centos/ checkmodule -M -m -o amusewiki.mod amusewiki.te semodule_package -o amusewiki.pp -m amusewiki.mod semodule -i amusewiki.pp
Reboot to be sure everything is ok, open with a browser the location you configured (say, amw.localdomain, you may want to add the entry /etc/hosts to access it) and login.
You probably want to head to the admin panel under /admin/sites to create a new site.