# Quickstart

## Installing bepasty

You can install bepasty either from PyPi (latest release) or from the git repository (latest available code).

    # from PyPi:
    pip install bepasty

    # if you'ld like to have python-magic to help determining files' mime types, use:
    pip install bepasty[magic]

    # from git repo
    pip install -e git+https://github.com/bepasty/bepasty-server.git#egg=bepasty-server

## Configuring bepasty

Before you can use bepasty, you need to carefully configure it (it won’t work in default configuration and most of the configuration settings need your attention).

When setting up permissions and giving out login secrets, carefully think about whom you give which permissions, especially when setting up the `DEFAULT_PERMISSIONS` (which apply to not-logged-in users).

Here is the documentation straight from its config:

class bepasty.config.Config

  This is the basic configuration class for bepasty.

  IMPORTANT:

  The config is only loaded at startup time of the app, so if you change it, you need to restart the wsgi app process(es) to make it load the updated config.

  APP_BASE_PATH = None

    base URL path of app (if not served on root URL, but e.g. on http://example.org/bepasty ). setting this to a non-None value will activate the PrefixMiddleware that splits PATH_INFO into SCRIPT_NAME (== APP_BASE_PATH) and the rest of PATH_INFO.

  ASCIINEMA_THEME = 'asciinema'

    The asciinema player theme (one of asciinema, tango, solarized-dark, solarized-light, monokai)

  DEFAULT_PERMISSIONS = ''

    not-logged-in users get these permissions - usually they are either no permissions (‘’) or read-only (‘read’).

  MAX_ALLOWED_FILE_SIZE = 5000000000

    The site admin can set some maximum allowed file size he wants to accept here. This is the maximum size an uploaded file may have.

  MAX_BODY_SIZE = 1040384

    The maximum http request body size. This is an information given to rest api clients so they can adjust their chunk size accordingly.

    This needs to be in sync with (or at least not beyond) the web server settings: apache: LimitRequestBody 1048576 # apache default is 0 (unlimited) nginx: client_max_body_size 1m; # nginx default (== 1048576)

  MAX_RENDER_SIZE = {'': 1000000, 'HIGHLIGHT_TYPES': 100000, 'application/pdf': 10000000, 'application/x-pdf': 10000000, 'audio/': 1000000000, 'image/': 20000000, 'text/x-bepasty-list': 38000, 'video/': 5000000000}

    Setup maximum file sizes for specific content-types. If an item is beyond the limit set for its type, it will not be rendered, but just offered for download. Lookup within MAX_RENDER_SIZE is done by first-match and it is automatically sorted for longer content-type- prefixes first.

    Format of entries: content-type-prefix: max_size

  PERMANENT_SESSION = False

    use a permanent session (True, cookie will expire after the given time, see below) or not (False, cookie will get removed when browser is closed)

  PERMANENT_SESSION_LIFETIME = 2678400

    lifetime of the permanent session (in seconds)

  PERMISSIONS = {}

    Bepasty does not use the usual user/password scheme, but only uses passwords (or passphrases - we’ll call both “a secret” below) as log-in credentials - there are no separate user names.

    People who log-in using such a secret may get more permissions than those who do not log-in (who just get DEFAULT_PERMISSIONS).

    Depending on the secret used to log-in, they will get the permissions configured here, see below.

    You can use same secret / same permissions for all privileged users or set up different secrets / different permissions for each user.

    If you want to be able to revoke permissions for some user / some group of users, it might be a good idea to remember to whom you gave which secret (and also handle it in a rather fine-grained way).

    PERMISSIONS is a dict that maps secrets to permissions, use it like:

        PERMISSIONS = {
            'myadminsecret_1.21d-3!wdar34': 'admin,list,create,modify,read,delete',
            'uploadersecret_rtghtrbrrrfsd': 'create,read',
            'joe_doe_89359299887711335537': 'create,read,delete',
        }

  SECRET_KEY = ''

    server secret key needed for safe session cookies. you must set a very long (20-100 chars), very random, very secret string here, otherwise bepasty will not work (and crash when trying to log in)!

  SESSION_COOKIE_SECURE = True

    transmit cookie only over https (if you use http, set this to False)

  SITENAME = 'bepasty.example.org'

    name of this site (put YOUR bepasty fqdn here)

  STORAGE = 'filesystem'

    Define storage backend, choose from:

    - ‘filesystem’

  STORAGE_FILESYSTEM_DIRECTORY = '/tmp/'

    Filesystem storage path

  UPLOAD_LOCKED = False

    Whether files are automatically locked after upload.

    If you want to require admin approval and manual unlocking for each uploaded file, set this to True.

To create a local and non-default configuration, copy `bepasty/config.py` to e.g. `/srv/bepasty/bepasty.conf` first, remove the `class Config` and remove all indents in the file. The comments can be removed too, if you feel the need to. At last modify these two configs variables: then modify it:

    # Note: no Config class required, just simple KEY = value lines:
    SECRET_KEY = '........................'
    STORAGE = 'filesystem'
    STORAGE_FILESYSTEM_DIRECTORY = '/srv/bepasty/storage/'
    # ...

Important notes:

- if you copied the file from the `bepasty/config.py` it will have a “class Config” in it and all the settings are inside that class. This is not what you need. Due to how flask config files work, you need to remove the class statement and outdent all the settings, so you just have global KEY = VALUE statements left on the top level of the config file.

- if you run over http (like for trying it locally / for development), you need to change the configuration to use SESSION_SECURE_COOKIE = False (otherwise you can not login as it won’t transmit the cookie over unsecure http).

## Starting bepasty server

You can run the bepasty server with your local configuration by pointing to it via the BEPASTY_CONFIG environment variable like this:

    BEPASTY_CONFIG=/srv/bepasty/bepasty.conf bepasty-server

Important note:

- Use an absolute path as value for BEPASTY_CONFIG.

The builtin WSGI server is recommended only for development and non-production use.

For production, you should use a WSGI server like gunicorn, apache+mod-wsgi, nginx+uwsgi, etc.

    gunicorn bepasty.wsgi

## Invoking CLI commands

All bepasty commands expect either a –config <configfilename> argument or that the BEPASTY_CONFIG environment variable points to your configuration file.

The “object” command operates on objects stored in the storage. You can get infos about them (“info” subcommand), you can set some flags on them (“set”), you can remove all or some (“purge”), you can check the consistency (“consistency”), etc…

To get help about the object command, use:

    bepasty-object --help

To get help about the object purge subcommand, use:

    bepasty-object purge --help

To run the object purge subcommand (here: dry-run == do not remove anything, files >= 10MiB AND age >= 14 days), use something like:

    bepasty-object purge --dry-run --size 10 --age 14 '*'

If you upgraded bepasty, you might need to upgrade the stored metadata to the current bepasty metadata schema:

    bepasty-object migrate '*'

Note: the ‘*’ needs to be quoted with single-quotes so the shell does not expand it. it tells the command to operate on all names in the storage (you could also give some specific names instead of ‘*’).