# Administration Guide

This guide is intended for administrators of an Anitya deployment.

## Installation

Anitya is not currently available in any distribution’s default repository. To install it from PyPI:

    $ pip install anitya

## Configuration

If the `ANITYA_WEB_CONFIG` environment variable is set to a file system path Anitya can read, the configuration is loaded from that location. Otherwise, the configuration is read from `/etc/anitya/anitya.toml`. If neither can be read, Anitya will log a warning and use its configuration defaults.

Warning

The default configuration for Anitya includes a secret key for web sessions. It is not safe to use the default configuration in a production environment.

Anitya uses TOML as its configuration format. A complete configuration file with inline documentation is below.

    # This is a TOML-format file. For the spec, see https://github.com/toml-lang/toml#spec

    # Secret key used to generate the CSRF token in the forms.
    secret_key = "changeme please"

    # The lifetime of the session, in seconds.
    permanent_session_lifetime = 3600

    # URL to the database
    db_url = "sqlite:////var/tmp/anitya-dev.sqlite"

    # List of web administrators. The values should be the value of the "id" column
    # for the user in the "users" table of the database. They need to log in before
    # this record is created. An example value would be
    # "65536ed7-bdd3-4a1e-8252-10d874fd706b"
    anitya_web_admins = []

    # The email to use in the 'From' header when sending emails.
    admin_email = "admin@fedoraproject.org"

    # The SMTP server to send mail through
    smtp_server = "smtp.example.com"

    # Whether or not to send emails to MAIL_ADMIN via SMTP_SERVER when HTTP 500
    # errors occur.
    email_errors = false

    # List of users that are not allowed to sign in, by "id" from the "users" table.
    blacklisted_users = []

    # The type of session protection used by social-auth.
    session_protection = "strong"

    # The authentication backends to use. For valid values, see social-auth's
    # documentation.
    social_auth_authentication_backends = [
        "social_core.backends.fedora.FedoraOpenId",
        "social_core.backends.gitlab.GitLabOAuth2",
        "social_core.backends.github.GithubOAuth2",
        "social_core.backends.google.GoogleOAuth2",
        "social_core.backends.yahoo.YahooOpenId",
        "social_core.backends.open_id.OpenIdAuth"
    ]

    # Force the application to require HTTPS on authentication redirects.
    social_auth_redirect_is_https = true

    # List of platforms for which Anitya should automatically create new projects
    # when Libraries.io announces a new version. See https://libraries.io/ for the
    # list of valid platforms. By default, Anitya will only update existing projects
    # via Libraries.io.
    librariesio_platform_whitelist = []
    sse_feed = "http://firehose.libraries.io/events"

    # Default regular expression used for backend
    default_regex = """\
                    (?i)%(name)s(?:[-_]?(?:minsrc|src|source))?[-_]([^-/_\\s]+?)(?:[-_]\
                    (?:minsrc|src|source|asc|release))?\\.(?:tar|t[bglx]z|tbz2|zip)\
                    """

    # Github access token
    # This is used by GitHub API for github backend
    github_access_token = "foobar"

    # The logging configuration, in Python dictConfig format.
    [anitya_log_config]
        version = 1
        disable_existing_loggers = true

        [anitya_log_config.formatters]
            [anitya_log_config.formatters.simple]
                format = "[%(name)s %(levelname)s] %(message)s"

        [anitya_log_config.handlers]
            [anitya_log_config.handlers.console]
                class = "logging.StreamHandler"
                formatter = "simple"
                stream = "ext://sys.stdout"

        [anitya_log_config.loggers]
            [anitya_log_config.loggers.anitya]
                level = "WARNING"
                propagate = false
                handlers = ["console"]

        [anitya_log_config.root]
            level = "ERROR"
            handlers = ["console"]

## Services

Anitya is made up of a WSGI application, an update script that should be run at regular intervals via cron or similar, an optional fedmsg consumer, and requires a database.

### WSGI Application

The WSGI application is located at `anitya.wsgi`. This application handles the web interface for creating, updating, and viewing projects. It also offers a REST API.

### Update Script

The script that checks for project updates is located at `files/anitya_cron.py` in the git repository and Python package.

### Libraries.io fedmsg Consumer

This optional service listens to a ZeroMQ socket for messages published by the libraries.io service. This requires that a bridge from Server-Sent Events (SSE) to ZeroMQ be running.

To run this, set the `anitya.libraryio.enabled` key to `True` in your fedmsg configuration and run the `fedmsg-hub` service.

### Database

Anitya should work with any SQL database, but it is only tested with SQLite and PostgreSQL. It is recommended to use PostgreSQL in a production deployment.