\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 <br><br> 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{Hacking on AmuseWiki}
\date{}
\author{Alexander Krotov}
\subtitle{}




% https://groups.google.com/d/topic/comp.text.tex/6fYmcVMbSbQ/discussion
\hypersetup{%
pdfencoding=auto,
pdftitle={Hacking on AmuseWiki},%
pdfauthor={Alexander Krotov},%
pdfsubject={},%
pdfkeywords={doc; howto}%
}


\begin{document}






  \begin{titlepage}


  \strut\vskip 2em
  \begin{center}

  {\usekomafont{title}{\huge Hacking on AmuseWiki\par}}%
  \vskip 1em
  
  \vskip 2em
  
  {\usekomafont{author}{Alexander Krotov\par}}%
  
  \vskip 1.5em



   
   \vfill



  
    \strut\par
  


  \end{center}


     \end{titlepage}
     
     \cleardoublepage



\tableofcontents
% start a new right-handed page

\cleardoublepage




This guide describes how to setup a development environment for AmuseWiki using \href{https://www.vagrantup.com/}{Vagrant}. Vagrant is a program that automates setting up virtual machines with development environments. Virtual machine is a good alternative to actually installing AmuseWiki and its dependencies on your computer.

\section{Installing Vagrant}


First, you need to install Vagrant and \href{https://www.virtualbox.org/}{VirtualBox}. Vagrant will manage virtual machine in VirtualBox.


On \href{https://www.debian.org/}{Debian}-based operating systems you can install Vagrant and VirtualBox by running (as a superuser)


\begin{alltt}
\# apt-get install vagrant virtualbox
\end{alltt}


You may need to reboot the system before running VirtualBox for the first time.


For other operating systems refer to \href{https://www.vagrantup.com/docs/installation/}{Vagrant documentation}.

\section{Obtaining the source code}


AmuseWiki source code is managed with \href{https://git-scm.com/}{Git}. On Debian-based systems you can install it with


\begin{alltt}
\# apt-get install git
\end{alltt}


To get the copy of source code, run (as normal user)


\begin{alltt}
\$ git clone https://github.com/melmothx/amusewiki
\end{alltt}


This will create \texttt{amusewiki} directory. It contains the \texttt{Vagrantfile}, which specifies how to setup a development environment for AmuseWiki. You don't need to read it, Vagrant does it for you.


To create and start the virtual machine, run


\begin{alltt}
\$ cd amusewiki
\$ vagrant up
\end{alltt}


On the first run, Vagrant will download the operating system image, called \href{https://www.vagrantup.com/docs/boxes.html}{box} in Vagrant terms. This may take some time.


When Vagrant is done setting up your development environment, point your web browser to \href{http://localhost:8080}{\texttt{http://localhost:8080}}. You will be present with AmuseWiki web interface, which asks you for login and password.

\section{Resetting AmuseWiki password}


AmuseWiki development environment comes with a preconfigured website with one user, \texttt{amusewiki}. Its password is generated randomly on setup, so you need to reset it in order to login.


To reset AmuseWiki password, run


\begin{alltt}
\$ vagrant ssh
\end{alltt}


It will connect to the virtual machine and present you with a shell prompt. To reset


\begin{alltt}
vagrant@debian-9:\textasciitilde{}\$ cd /vagrant
vagrant@debian-9:/vagrant\$ script/amusewiki-reset-password amusewiki
\end{alltt}


On the first line we change the working directory to \texttt{/vagrant}. \texttt{/vagrant} inside the virtual machine is the same directory as the directory with the source code on the host machine. It is automatically synchronized.


On the second line we reset the password for the \texttt{amusewiki} user. It will output something like


\begin{alltt}
vagrant@debian-9:/vagrant\$ carton exec script/amusewiki-reset-password amusewiki
Password for amusewiki is now 'correct horse battery staple'
\end{alltt}


Then, you can login as \texttt{amusewiki} with the password \texttt{correct horse battery staple} in your web browser.

\section{Changing the source code}


As the repository is mounted into \texttt{/vagrant} inside the virtual machine, any modifications to the code will immediately affect the running web application. Good place to start is to try modifying web page templates, which are stored in \texttt{amusewiki/root/src/}.

\section{Running test suite}


To run the test suite, use


\begin{alltt}
vagrant@debian-9:/vagrant\$ carton exec prove -l
\end{alltt}


If some tests are failing, they will be reported in the end:


\begin{alltt}
...
Test Summary Report
-------------------
t/full-blog-mode.t              (Wstat: 256 Tests: 228 Failed: 1)
  Failed test:  166
  Non-zero exit status: 1
t/xapian.t                      (Wstat: 1024 Tests: 43 Failed: 4)
  Failed tests:  26-29
  Non-zero exit status: 4
...
\end{alltt}


To rerun a particular test suite, for example \texttt{t/full-blog-mode.t}, use


\begin{alltt}
vagrant@debian-9:/vagrant\$ carton exec prove -vl t/full-blog-mode.t
\end{alltt}

\section{Stopping the development environment}


When done, you can suspend the virtual machine by running


\begin{alltt}
\$ vagrant suspend
\end{alltt}


or shutdown it completely with


\begin{alltt}
\$ vagrant halt
\end{alltt}


To resume the development environment, simply run


\begin{alltt}
\$ vagrant up
\end{alltt}


again.


If you want to reinstall your development environment from scratch, you can delete the virtual machine by running


\begin{alltt}
\$ vagrant destroy
\end{alltt}


All your code modifications will be left intact, as they are stored in the shared folder. You can then commit them and submit a pull request.

\section{Cleaning the workdir}


Even though you want to keep your modifications, you may want to remove modifications made automatically, such as creation of the SQLite database. Such automatically created files are already listed in \texttt{.gitignore}. You can remove them with


\begin{alltt}
\$ git clean -dffX
\end{alltt}


Don't confuse \texttt{-X} switch with \texttt{-x}! \texttt{-X} removes \emph{only} the files from .gitignore, while \texttt{-x} also removes untracked files created by you. The safest way is to


\begin{alltt}
git stash
\end{alltt}


or commit your modifications before cleanup.

\section{Where to go from here}


To learn more about Vagrant, start by reading the \href{https://www.vagrantup.com/intro/getting-started/}{Getting Started} guide.


AmuseWiki built with \href{http://www.catalystframework.org/}{Catalyst framework} and \href{https://getbootstrap.com/}{Bootstrap}. Depending on the area you want to modify, you may want to learn more about these technologies.


Happy hacking.







% 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}


Alexander Krotov

Hacking on AmuseWiki






\bigskip



   

       

       

       

       

       
   



\bigskip
\textbf{amusewiki.org}


\end{center}

% end final page with colophon


\end{document}


% No format ID passed.



