FreedomBox/doc/plinth.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.docbook.org/xml/4.4/docbookx.dtd">
<!--
#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
-->
<refentry>
  <refmeta>
    <refentrytitle><application>plinth</application></refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="manual">FreedomBox</refmiscinfo>
    <refmiscinfo class="version"> </refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>plinth</application></refname>
    <refpurpose>
      a web front end for administering FreedomBox
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>plinth</command>
      <arg><option>-h, </option><option>--help</option></arg>
      <arg><option>--server_dir</option><arg choice="req">SERVER_DIR</arg></arg>
      <arg><option>--debug</option></arg>
      <arg><option>--diagnose</option></arg>
      <arg>
        <option>--setup</option>
        <arg choice="opt" rep="repeat">application</arg>
      </arg>
      <arg>
        <option>--setup-no-install</option>
        <arg choice="opt" rep="repeat">application</arg>
      </arg>
      <arg>
        <option>--list-dependencies</option>
        <arg choice="opt" rep="repeat">application</arg>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      FreedomBox is a community project to develop, design and promote
      personal servers running free software for private, personal
      communications.  It is a networking appliance designed to allow
      interfacing with the rest of the Internet under conditions of
      protected privacy and data security.  It hosts applications such
      as blog, wiki, website, social network, email, web proxy and a
      Tor relay on a device that can replace a wireless router so that
      data stays with the users.
    </para>
    <para>
      Plinth is a web interface to administer the functions of the
      FreedomBox.  It is extensible and is made of modules.  Each
      module provides a simplified user interface to control the
      underlying functionality of a specific application of
      FreedomBox.  As FreedomBox can act as a wireless router, it is
      possible to configure networking from Plinth.  Plinth allows
      configuration of basic system parameters such as time zone,
      hostname and automatic upgrade settings.
    </para>
  </refsect1>

  <refsect1>
    <title>Options</title>
    <variablelist>
      <varlistentry>
        <term><option>--server_dir SERVER_DIR</option></term>
        <listitem>
          <para>
            This the URL fragment under which Plinth will provide its
            services.  By default the value from
            <filename>plinth.config</filename> is used.  Plinth is
            shipped with a value of <filename>/plinth</filename> in
            <filename>/etc/plinth/plinth.config</filename>.  This
            means that Plinth will be available as
            http://localhost:8000/plinth by default.  When
            <filename>/etc/plinth/plinth.config</filename> is not
            available, <filename>plinth.config</filename> from current
            directory is used.  In source directory, this has the
            default value of <filename>/</filename>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--debug</option></term>
        <listitem>
          <para>
            Enable debug mode.  Turn off Django security features.
            Print extra debug messages.  Monitor source files for
            changes and restart Plinth on modifications.  Turn on
            Django debug mode to show details on error pages.  Die if
            there is an error during module initialization.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--diagnose</option></term>
        <listitem>
          <para>
            If provided, Plinth loads modules, performs initialization
            but does start the web server.  Instead it runs diagnostic
            tests on each module and exits.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--setup</option></term>
        <listitem>
          <para>
            Perform application setup operations and exit.  Setting up
            an application involves installing packages required for
            that application and performing pre and post install
            configuration setups.  If no application is provided,
            setup all applications which describe themselves as
            essential.  If a list of applications is provided, setup
            only those applications.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--setup-no-install</option></term>
        <listitem>
          <para>
            Same as <option>--setup</option> but no new Debian
            packages are installed during setup.  When a package needs
            to be installed, a check is done to make sure the package
            is already installed.  If the package is already
            installed, no upgrade is performed and setup skips this
            step and proceeds to next operation.  If the package is
            not installed an error is raised and setup process halts.
            This is option is useful for running setup during post
            installation script of a Debian package.  Essential
            packages are added as dependencies for the Debian package
            and then setup process is executed from post install
            script of the Debian package.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--list-dependencies</option></term>
        <listitem>
          <para>
            For the list of provided applications, print the list of
            packages needed by the applications.  If no application is
            provided as additional argument, then print list of
            packages needed by all essential applications.  If '*' is
            provided in the list of the applications, then list of
            packages needed by all applications will be printed.
            Although, packages are installed when the application is
            first accessed, this list will be useful for adding list
            of dependencies to a Debian package and to get a list of
            all interesting packages.  Other output may be printed on
            stderr and should be ignored.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Configuration</title>
    <para>
      Plinth reads various configuraiton options from the file
      <filename>/etc/plinth/plinth.config</filename>.  If this file is
      not present, then it reads configuration file
      <filename>./plinth.config</filename> from the current directory.
      This is mainly meant to make Plinth work with configuration from
      source code directory for debugging purposes.
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <example>
      <title>Start Plinth with default options</title>
      <synopsis>$ plinth</synopsis>
      <para>
        Run Plinth as guided by configuration file.
      </para>
    </example>

    <example>
      <title>Run Plinth for debugging</title>
      <synopsis>$ plinth --server_dir=/plinth --debug</synopsis>
      <para>
        Enable debug mode and run on terminal.  Also override the
        configuration file value for the URL fragment to start Plinth
        under and set it to /plinth.
      </para>
    </example>
  </refsect1>

  <refsect1>
    <title>Bugs</title>
    <para>
      See <ulink
      url="https://salsa.debian.org/freedombox-team/plinth/issues">Plinth
      issue tracker</ulink> for a full list of known issues and TODO items.
    </para>
  </refsect1>

  <refsect1>
    <title>Author</title>
    <para>
      <author>
        <firstname>Plinth Developers</firstname>
        <contrib>Original author</contrib>
      </author>
    </para>
  </refsect1>
</refentry>