Guide for installing and maintaining a [[https://wallabag.org/|Wallabag]] instance. Wallabag is a self-hosted alternative to pocket that integrates well with [[https://koreader.rocks/|KOReader]].

<<TableOfContents>>

== Installation ==

=== Create the database ===

You can use either MySQL or PostgreSQL. You'll need to create a database for wallabag. The name is arbitrary but in this guide we'll be using a mysql database named `wallabag` (PostgreSQL support appeared to be less robust as of July 2020):

{{{
dbtool mysql createdb wallabag
}}}

=== Install and Run Setup Script ===

Wallabag runs from its source directory. Check the code out to wherever you want to store the webapps (except for `~/public_html`). In this guide we'll be using `~/webapps/wallabag`. 

First, checkout the source code and build the application.

{{{
git clone https://github.com/wallabag/wallabag.git ~/webapps/wallabag
cd ~/webapps/wallabag
make
}}}

The Makefile will ask you several questions, the important values to set are (substitute `YOU` for your username, and `YOUR-WALLABAG-DOMAIN` for the domain you are installing wallabag on):

{{{
database_driver: mysql
database_host: mysql.hcoop.net
database_name: YOU_wallabag
database_user: YOU
database_password: YOUR MYSQL PASSWORD
domain_name: https://YOUR-WALLABAG-DOMAIN
twofactor_sender: no-reply@YOUR-WALLABAG-DOMAIN
fosuser_registration: false
from_email: no-reply@YOUR-WALLABAG-DOMAIN
}}}

Use `http` for your domain if you will not be [[MemberManual/ServingWebsites/SslCert|using TLS]].

When the Makefile gets to the database creation step, it may ask you if you want to reset the database. Answer `no` and it will create the schema (answering yes just causes it to attempt to drop the database, which fails). If you need to reset the database entirely, you'll need to drop and re-create it using `dbtool`

It will then ask if you would like to setup an admin user, you generally should. Choose an appropriate username and password, and '''do not use the insecure defaults'''. 

=== Set Permissions ===

The application will need to read the source tree, and write to `~/webapps/wallbag/var` as your daemon user. Additionally, it will attempt to store session in `~/webapps/wallabag/var/sessions/prod, but PHP cannot write session files into AFS, so we symlink that to the shared sessions directory on the webserver's local filesystem. Set the appropriate openafs acls and symlinks:

{{{
fsr sa ~/webapps/wallabag/ $USER.daemon read
fsr sa ~/webapps/wallabag/var/ $USER.daemon write
mkdir -p ~/webapps/wallabag/var/sessions ; rm -rf ~/webapps/wallabag/var/sessions/prod ; ln -s  /var/lib/php/sessions/ ~/webapps/wallabag/var/sessions/prod
}}}

=== Domtool Configuration ===

This example assumes you'll be installing it as a subdomain named `wallabag` of another domain. Inside of the `dom` container for your domain:

{{{
  web "wallabag" where
    DocumentRoot = home "webapps/wallabag/web";
    SSL = YOUR SSL CERT;
  with
    location "/" with
      setEnvIf "Authorization" "(.*)" ["HTTP_AUTHORIZATION=$1"];
   
      rewriteCond "%{REQUEST_FILENAME}" "!-f" [];
      rewriteRule "." "app.php" [qsappend,last];
    end;
  end;
}}}

== Upgrading ==

(NB: untested)

{{{
make update
}}}

== Additional Material ==

 * [[https://github.com/wallabag/wallabag|Upstream source code]]
 * [[https://doc.wallabag.org/|Wallabag documentation]]
 * [[https://doc.wallabag.org/en/admin/installation/installation.html|Upstream installation manual]]
 * [[https://doc.wallabag.org/en/admin/upgrade.html|Upstream upgrade guide]]

----
CategoryMemberManual