aurweb/INSTALL

Setup on Arch Linux
===================

For testing aurweb patches before submission, you can use the instructions in
TESTING for testing the web interface only.

Note that you can only do limited testing using the PHP built-in web server.
In particular, the cgit interface will be unusable as well as the ssh+git
interface. For a detailed description on how to setup a full aurweb server,
read the instructions below.

1) Clone the aurweb project:

   $ cd /srv/http/
   $ git clone git://git.archlinux.org/aurweb.git

2) Setup a web server with PHP and MySQL. Configure the web server to redirect
   all URLs to /index.php/foo/bar/. The following block can be used with nginx:

    server {
        listen       80;
        server_name  aur.local aur;

        root   /srv/http/aurweb/web/html;
        index  index.php;

        location ~ ^/[^/]+\.php($|/) {
            fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
            fastcgi_index  index.php;
            fastcgi_split_path_info ^(/[^/]+\.php)(/.*)$;
            fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
            fastcgi_param  PATH_INFO        $fastcgi_path_info;
            include        fastcgi_params;
        }

        location ~ .* {
            rewrite ^/(.*)$ /index.php/$1 last;
        }
    }

    Ensure to enable the pdo_mysql extension in php.ini.

3) Optionally copy conf/config.defaults to /etc/aurweb/. Create or copy
   /etc/aurweb/config (this is expected to contain all configuration settings
   if the defaults file does not exist) and adjust the configuration (pay
   attention to disable_http_login, enable_maintenance and aur_location).

4) Install dependencies.

4a) Install system-wide dependencies:

    # pacman -S git gpgme cgit pyalpm python-srcinfo curl openssh \
                uwsgi uwsgi-plugin-cgi php php-fpm

4b) Install Python dependencies via poetry (required):

**NOTE** Users do not need to install pip or poetry dependencies system-wide.
You may take advantage of Poetry's virtualenv integration to manage
dependencies. This is merely a demonstration to show users how to without
a virtualenv. In Docker and CI, we don't yet use a virtualenv.

    ## Install Poetry dependencies system-wide, if not using a virtualenv.
    # pacman -S python-pip

    ## Ensure pip is upgraded. Poetry depends on it being up to date.
    # pip install --upgrade pip

    ## Install Poetry.
    # curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
    # export PATH="$HOME/.poetry/bin:${PATH}"

    ## Use Poetry to install dependencies and the aurweb package.
    # poetry lock     # Resolve dependencies
    # poetry update   # Install/update dependencies
    # poetry build    # Build the aurweb package
    # poetry install  # Install the aurweb package and scripts

When installing in a virtualenv, config.defaults must contain the correct
absolute paths to aurweb scripts, which requires modification.

4c) Setup FastAPI Redis cache (optional).

First, install Redis and start its service.

    # pacman -S redis
    # systemctl enable --now redis

Now that Redis is running, ensure that you configure aurweb to use
the Redis cache by setting `cache = redis` in your AUR config.

In `conf/config.defaults`, the `redis_address` configuration is set
to `redis://localhost`. This can be set to point to any Redis server
and will be used as long as `cache = redis`.

5) Create a new database and a user and import the aurweb SQL schema:

    $ python -m aurweb.initdb

6) Create a new user:

    # useradd -U -d /srv/http/aurweb -c 'AUR user' aur

7) Initialize the Git repository:

    # mkdir /srv/http/aurweb/aur.git/
    # cd /srv/http/aurweb/aur.git/
    # git init --bare
    # git config --local transfer.hideRefs '^refs/'
    # git config --local --add transfer.hideRefs '!refs/'
    # git config --local --add transfer.hideRefs '!HEAD'
    # ln -s /usr/local/bin/aurweb-git-update hooks/update
    # chown -R aur .

   It is recommended to read doc/git-interface.txt for more information on the
   administration of the package Git repository.

8) Configure sshd(8) for the AUR. Add the following lines at the end of your
   sshd_config(5) and restart the sshd. Note that OpenSSH 6.9 or newer is
   needed!

    Match User aur
        PasswordAuthentication no
        AuthorizedKeysCommand /usr/local/bin/aurweb-git-auth "%t" "%k"
        AuthorizedKeysCommandUser aur
        AcceptEnv AUR_OVERWRITE

9) If you want to enable smart HTTP support with nginx and fcgiwrap, you can
   use the following directives:

    location ~ "^/([a-z0-9][a-z0-9.+_-]*?)(\.git)?/(git-(receive|upload)-pack|HEAD|info/refs|objects/(info/(http-)?alternates|packs)|[0-9a-f]{2}/[0-9a-f]{38}|pack/pack-[0-9a-f]{40}\.(pack|idx))$" {
        fastcgi_pass   unix:/run/fcgiwrap.sock;
        include        fastcgi_params;
        fastcgi_param  SCRIPT_FILENAME /usr/lib/git-core/git-http-backend;
        fastcgi_param  PATH_INFO /aur.git/$3;
        fastcgi_param  GIT_HTTP_EXPORT_ALL "";
        fastcgi_param  GIT_NAMESPACE $1;
        fastcgi_param  GIT_PROJECT_ROOT /srv/http/aurweb/;
    }

   Sample systemd unit files for fcgiwrap can be found under conf/.

10) If you want memcache to cache MySQL data.

    # pacman -S php-memcached

    And edit the configuration file to enabled memcache caching.