.. _configuration: Configuration ############# ``pinnwand`` is configured in three ways, one is by arguments and the other is through a configuration file and the last is by environment variables. The options available are dependent on the command you're running. You can always pass the ``--configuration-path`` argument to ``pinnwand``. Here is a quick example:: pinnwand --configuration-path /tmp/foo.toml http --port 9000 The ``http`` subcommand takes a separate argument ``--port`` to override the default listening port (8000). Any value in this file can be overriden by setting its equivalent in the environment or in a `.env` file. To do that, all environment variables need to be in the form of `PINNWAND_{{option}}`. For example, if we wanted to override the `database_uri` option, we will define our value like the following:: PINNWAND_DATABASE_URI="hello" .. note:: * Any variable in the actual environment will take precedence over its equivalent in the `.env` file. * It's best to place the `.env` at the root directory of the project, to avoid including it into VCS. File **** The configuration file has a bunch more properties to configure ``pinnwand`` with. Here's an example file:: # Example configuration file for `pinnwand`. Shows what you can adjust. More # information can be found at `pinnwand`'s documentation: # https://pinnwand.readthedocs.io/en/latest/ or you can file an issue at our # GitHub: https://github.com/supakeen/pinnwand # Database URI to connect to see: https://docs.sqlalchemy.org/en/13/core/engines.html#database-urls # if you want to use databases other than sqlite be sure to install the # appropriate packages and then format this url to correspond to them. database_uri = "sqlite:///:memory:" # Maximum paste size you want to allow. paste_size = 262144 # 256kB in bytes # Preferred lexers. This list of lexers will appear on top of the dropdown # on the website allowing you to preselect commonly used lexers. Note that the # names here have to be the identifiers used by pygments, not the human names. # The keys returned by /api/v1/lexer are an exhaustive list of supported lexers. # If empty no preferred lexers are shown. preferred_lexers = [] # The lexer selected by default when creating a new paste. # Similar to preferred_lexers, only supports lexer identifiers used by pygments. default_selected_lexer = "text" # Logo path, used to render your logo. If left out the default logo will be # used. This file must be a png file. # logo_path = "/path/to/a/file.png" # The page path is used to find the pages listed in the page_list page_path = "/tmp" # This is the whitelist of files that should exist in the `page_path` # configuration directive. `pinnwand` will look for `$file.rst` in the # `page_path` directory and serve it at `/$file`. page_list = ["about", "removal", "expiry"] # The footer in raw HTML, shown at the bottom of the page and handy to link to # your previously configured pages. footer = 'View source code, the removal or expiry stories, or read the about page.' # HTML for the 'help text' that can be shown above the paste area, if left # empty no help text will be shown. paste_help = "

Welcome to pinnwand, this site is a pastebin. It allows you to share code with others. If you write code in the text area below and press the paste button you will be given a link you can share with others so they can view your code as well.

People with the link can view your pasted code, only you can remove your paste and it expires automatically. Note that anyone could guess the URI to your paste so don't rely on it being private.

" # Email used for file reporting. If the value is not None then a href with a mailto link will be added to every paste page thus allowing the users to report pastes that may need removal. report_email = "maintainer@example.com" # Expiries are given by a name and their duration in seconds, if you want to do # 'forever' set a really large number... expiries.1hour = 3600 expiries.1day = 86400 expiries.1week = 604800 # These are application level ratelimits, if you use proxies for your pinnwand # instance you should set limits there as well. These limits describe a token # bucket and are per-IP. # # The capacity is how many tokens there are available, the consumption is how # many tokens are used by an action and the refill is how many tokens are added # per second. So the read bucket below allows a burst of a 100 reads then another # 2 per second. ratelimit.read.capacity = 100 ratelimit.read.consume = 1 ratelimit.read.refill = 2 ratelimit.create.capacity = 2 ratelimit.create.consume = 2 ratelimit.create.refill = 1 ratelimit.delete.capacity = 2 ratelimit.delete.consume = 2 ratelimit.delete.refill = 1 # pinnwand uses a naive anti-spam measure where a regex is ran over the text # that is pasted. It then checks how large a percentage of the incoming bytes # consist of links. If that percentage is larger than the number below the # paste is denied. Set to a 100 to disable. spamscore = 50 # pinnwand has a background job that deletes all expired pastes in order to not have an overloaded database. # The period every which the task is executed is expressed in milliseconds reaping_periodicity = 1_800_000 Options ******* database_uri ============ A URI as accepted by sqlalchemy for the database to use. Default: ``sqlite:///:memory``` paste_size ========== Maximum size of a formatted paste. This includes the HTML as generated by pygments. The size should be supplied in bytes. Default: ``262144`` (256 kB). preferred_lexers ================ The lexers that are shown on the homepage above all other lexers. This allows you to customize your homepage to the most-used lexers for your users. Leaving this list empty will not show any preferred lexers. The lexer names in this list must be supported by pygments. Default: ``[]``. default_selected_lexer ====================== The lexer that is selected by default when creating a new paste. Default: ``text`` logo_path ========= Path to a custom logo file. Needs to be readable by the user ``pinnwand`` runs as. Leave out of the configuration file if you want to use the default logo. Default: ``unset``. page_path ========= A filesystem path where pages listed in ``page_path`` are looked up in. If unset the default ``pinnwand`` path will be used. Default: ``unset``. page_list ========= List of static text pages. If set these pages will be looked up in the ``page_path`` variable. These files should exist in ``page_path`` with a ``.rst`` suffix. Default: ``["about", "removal", "expiry"]`` footer ====== HTML to render in the footer. Default: ``bunch of html`` paste_help ========== HTML to render above the new paste page to help users on how to use your instance. Default: ``bunch of html`` report_email ============ An email address that allows users to report a paste that may need removal or edition. Default: ``None`` expiries ======== Several expiries exist, these are shown in the drop down by name and are used for reaping pastes. They are denoted in seconds and the keys are free to choose. expiries.1hour ^^^^^^^^^^^^^^ Default: `3600` expiries.1day ^^^^^^^^^^^^^ Default: `86400` expiries.1week ^^^^^^^^^^^^^^ Default: `604800` ratelimit ========= These are application level ratelimits, if you use proxies for your pinnwand instance you should set limits there as well. These limits describe a token bucket and are per-IP. The capacity is how many tokens there are available, the consumption is how many tokens are used by an action and the refill is how many tokens are added per second. So the read bucket below allows a burst of a 100 reads then another 2 per second. ratelimit.read.capacity ^^^^^^^^^^^^^^^^^^^^^^^ Default: `100` ratelimit.read.consume ^^^^^^^^^^^^^^^^^^^^^^ Default: `1` ratelimit.read.refill ^^^^^^^^^^^^^^^^^^^^^ Default: `2` ratelimit.create.capacity ^^^^^^^^^^^^^^^^^^^^^^^^^ Default: `2` ratelimit.create.consume ^^^^^^^^^^^^^^^^^^^^^^^^ Default: `2` ratelimit.create.refill ^^^^^^^^^^^^^^^^^^^^^^^ Default: `1` ratelimit.delete.capacity ^^^^^^^^^^^^^^^^^^^^^^^^^ Default: `2` ratelimit.delete.consume ^^^^^^^^^^^^^^^^^^^^^^^^ Default: `2` ratelimit.delete.refill ^^^^^^^^^^^^^^^^^^^^^^^ Default: `1` spamscore ========= pinnwand uses a naive anti-spam measure where a regex is ran over the text that is pasted. It then checks how large a percentage of the incoming bytes consist of links. If that percentage is larger than the number below the paste is denied. Set to a 100 to disable. Default: `50` reaping_periodicity ========= pinnwand has a background job that deletes all expired pastes in order to not have an overloaded database. The period every which the job is executed is expressed in milliseconds Default: `1_800_000`