# Available Fabric commands

New in version 2.5: Starting in this release, Pootle includes Fabric deployment scripts.

## Introduction

The sample Fabric scripts provide several commands that you can use to easily deploy your Pootle site.

Note

Most of the examples in this section will use the `production` environment, but remember that other environments can be used as well.

Please read first the How to run Fabric commands section in order to know how this commands can be run. Reading the Typical Usage Example section might be helpful as well.

## Available commands

### bootstrap

This command:

- Creates the required directories, asking to remove them first if they already exist
- Creates a virtual environment (virtualenv) and activates it
- Clones the Pootle repository from GitHub
- Checks out the specified branch, using master if no branch is specified
- Installs the deployment requirements as listed in `requirements/`, including the base requirements as well

Note

While running it may ask for the remote server `root` password, or more likely the `sudo` password, which is the standard password for the remote user configured in the environment.

Note

Changed in version 2.5.1: Added support for bootstrapping from a given branch on Pootle repository.

Examples:

    $ fab production bootstrap  # Call that will use the default 'master' branch
    $ fab production:branch=stable/2.5.0 bootstrap  # Call which provides a branch

### compile_translations

This command:

- Compiles the MO files for Pootle translations

Examples:

    $ fab production compile_translations

### create_db

New in version 2.5.1.

This command:

- Creates a new blank database using the settings provided to Fabric in the chosen environment

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment) as well as the specified `db_user` and/or database root password. See the mysql_conf command for a way to eliminate the need for database password prompting.

Note

This command will try to create a database on MySQL, which will fail if MySQL is not installed or the settings don’t provide configuration data for creating the database.

Examples:

    $ fab production create_db

### deploy

This command:

- Calls the update_code command
- Calls the syncdb command
- Calls the migratedb command
- Calls the deploy_static command
- Calls the install_site command

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment).

Note

Changed in version 2.5.1: Added support for deploying from a given branch on Pootle repository.

Examples:

    $ fab production deploy  # Call that will use the default 'master' branch
    $ fab production:branch=stable/2.5.0 deploy  # Call which provides a branch

### deploy_static

This command:

- Creates `pootle/assets/` directory if it does not exist
- Runs collectstatic –noinput –clear to collect the static files
- Runs assets build to create the assets

Examples:

    $ fab production deploy_static

### disable_site

This command:

- Disables the Pootle site on Apache using the Apache a2dissite command

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment).

Examples:

    $ fab production disable_site

### drop_db

New in version 2.5.1.

This command:

- Drops a database (losing all data!) using the settings provided to Fabric in the chosen environment

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment) as well as the specified `db_user` and/or database root password. See the mysql_conf command for a way to eliminate the need for database password prompting.

Examples:

    $ fab production drop_db

### drop_deployment

New in version 2.6.0.

This command:

- Calls the disable_site command
- Calls the drop_db command
- Removes the configuration files created by the update_config command
- Removes the directories created during the deployment, including the ones holding the translation files and the repositories for those translation files

Note

This command is capable of removing uncompleted deployments.

Note

While running it may ask for the remote server `root` password and the specified `db_user` password.

Examples:

    $ fab production drop_deployment

### dump_db

New in version 2.5.1.

This command:

- Dumps the database to the provided filename using the mysqldump command
- Downloads the dumpfile to the local computer

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment) as well as the specified `db_user` and/or database root password. See the mysql_conf command for a way to eliminate the need for database password prompting.

Note

This commands can be used to perform periodic backups, that can be imported later using the load_db command.

Available arguments:

`dumpfile`

  The local filename for the file where the database will be dumped.

  Default: `pootle_DB_backup.sql`.

Examples:

    $ fab production dump_db  # Call that will use the default filename
    $ fab production dump_db:dumpfile=backup_mysql.sql  # Call which provides a filename

### enable_site

This command:

- Enables the Pootle site on Apache using the Apache a2ensite command

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment).

Examples:

    $ fab production enable_site

### initdb

New in version 2.5.1.

This command:

- Runs initdb to initialize the database

Examples:

    $ fab production initdb

### install_site

This command:

- Calls the update_config command
- Calls the enable_site command

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment).

Examples:

    $ fab production install_site

### load_db

New in version 2.5.1.

This command:

- Uploads the given SQL dump file to the remote server
- Imports it to the database specified on Fabric settings using the mysql command

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment) as well as the specified `db_user` and/or database root password. See the mysql_conf command for a way to eliminate the need for database password prompting.

Note

You must first create the database you will import (e.g. using the create_db command) before calling this command,

Available arguments:

`dumpfile`

  The local SQL dump filename that will be uploaded to the remote server and imported into an existing database on the remote server. This file can be created using the dump_db command.

  Note

  This is a required argument.

Examples:

    $ fab production create_db  # Remember to create the DB first
    $ fab production load_db:dumpfile=backup_mysql.sql

### migrate_app

New in version 2.6.0.

This command:

- Runs migrate to run the migrations for the specified Pootle app

Available arguments:

`appname`

  The name of the Pootle app for which the migrations should be run for.

  Note

  This is a required argument.

Examples:

    $ fab production migrate_app:appname=pootle_store

### migratedb

New in version 2.5.1.

This command:

- Runs migrate to update the 2.5 or later database schema to the latest version

Examples:

    $ fab production migratedb

### mysql_conf

New in version 2.5.1.

This command creates a `.my.cnf` MySQL options file on the remote system with the password(s) for database access stored in them (the passwords are taken from the `fabric.py` settings file). Once you have done this, you can un-comment the alternate `db_password_opt` and `db_root_password_opt` settings in `fabric.py`, which will eliminate the need for password prompting on all MySQL operations.

Examples:

    $ fab production mysql_conf

### production

This command:

- Sets up the configuration for the `production` environment in Fabric settings

Note

This command is useless unless it is called before another command or commands.

Note

This command allows changing the settings. To do so just pass it any of its arguments when calling it.

Note that some commands might require passing any or all of these arguments to this command in order to overwrite the default settings before calling those commands. For example the command stage_feature requires passing `branch`, `repo` and `feature`.

Note

Changed in version 2.5.1: Added support for altering the settings based on the passed arguments.

Available arguments:

`branch`
  A specific branch to check out in the repository.
`repo`

  A repository URL to clone from.

  This allows to checkout from a fork repository (not necessarily on GitHub) and try new features developed on that repository. It must be an URL that the `git clone` command is able to clone.

`feature`
  Allows specifying if the deployment is for a feature-staging server. Such servers are used by Pootle developers in order to allow quick test of new features using a live Pootle server.

Examples:

    $ fab production bootstrap

In the previous example production is called to set up the environment for calling bootstrap afterwards.

    $ fab production:branch=feature/extension-actions bootstrap

In the previous example production is called to set up the environment for calling bootstrap afterwards.

The `branch` argument overwrites the default branch in the settings, which are then used for all the subsequent commands (just bootstrap in this example).

    $ fab production:branch=feature/extension-actions,repo=git://github.com/unho/pootle.git bootstrap

In the previous example production is called to set up the environment for calling bootstrap afterwards.

The `branch` and `repo` arguments overwrite the default settings, which are then used for all the subsequent commands (just bootstrap in this example).

    $ fab production:branch=feature/extension-actions,repo=git://github.com/unho/pootle.git,feature=yes stage_feature

This example is like the previous one, with the addition of the `feature` argument that triggers the altering of several settings. That altering is necessary for working with feature-staging servers.

### send_file

New in version 2.6.0.

This command:

- Uploads the specified file to the server

Available arguments:

`upfile`

  The name of the file to upload.

  Note

  This is a required argument.

Examples:

    $ fab production send_file:upfile=translation-files.tar.gz

### setup

New in version 2.5.1.

This command:

- Runs setup to create or upgrade the database as required

Examples:

    $ fab production setup

### setup_db

New in version 2.5.1.

This command:

- Runs syncdb –noinput to create the database schema
- Runs initdb to populate the standard schema objects
- Runs migrate to bring the database schema up to the latest version

Examples:

    $ fab production setup_db

### stage_feature

New in version 2.5.1.

This command:

- Calls the bootstrap command
- Calls the create_db command
- Copies the data in the specified source DB into the DB that will be used for the deployed Pootle
- Calls the update_db command
- Calls the deploy_static command
- Calls the install_site command

Note

While running it may ask for the remote server `root` password and the specified `db_user` password.

Note

This command is intended primarily for deploying ad-hoc Pootle servers for easing the test of feature branches during Pootle development.

Warning

This command might require changing the source_db field in the `deploy/ENVIRONMENT/fabric.py` file. Note that the database specified on this field must exist.

Warning

This command requires using the `staging` environment passing to it the `feature` argument, the desired branch and optionally a repository URL.

Examples:

    $ fab staging:branch=feature/extension-actions,feature=yes stage_feature
    $ fab staging:branch=feature/extension-actions,repo=git://github.com/unho/pootle.git,feature=yes stage_feature

### staging

This command:

- Sets up the configuration for the `staging` environment in Fabric settings

Note

This command is useless unless it is called before another command or commands.

Note

This command allows changing the settings. To do so just pass it any of its arguments when calling it.

Note that some commands might require passing any or all of these arguments to this command in order to overwrite the default settings before calling those commands. For example the command stage_feature requires passing `branch`, `repo` and `feature`.

Note

Changed in version 2.5.1: Added support for altering the settings based on the passed arguments.

Available arguments:

`branch`
  A specific branch to check out in the repository.
`repo`

  A repository URL to clone from.

  This allows to checkout from a fork repository (not necessarily on GitHub) and try new features developed on that repository. It must be an URL that the `git clone` command is able to clone.

`feature`
  Allows specifying if the deployment is for a feature-staging server. Such servers are used by Pootle developers in order to allow quick test of new features using a live Pootle server.

Examples:

    $ fab staging bootstrap

In the previous example staging is called to set up the environment for calling bootstrap afterwards.

    $ fab staging:branch=feature/extension-actions bootstrap

In the previous example staging is called to set up the environment for calling bootstrap afterwards.

The `branch` argument overwrites the default branch in the settings, which are then used for all the subsequent commands (just bootstrap in this example).

    $ fab staging:branch=feature/extension-actions,repo=git://github.com/unho/pootle.git bootstrap

In the previous example staging is called to set up the environment for calling bootstrap afterwards.

The `branch` and `repo` arguments overwrite the default settings, which are then used for all the subsequent commands (just bootstrap in this example).

    $ fab staging:branch=feature/extension-actions,repo=git://github.com/unho/pootle.git,feature=yes stage_feature

This example is like the previous one, with the addition of the `feature` argument that triggers the altering of several settings. That altering is necessary for working with feature-staging servers.

### syncdb

New in version 2.5.1.

This command:

- Runs syncdb –noinput to create the database schema

Examples:

    $ fab production syncdb

### touch

This command:

- Reloads daemon processes by touching the WSGI file

Examples:

    $ fab production touch

### unstage_feature

Changed in version 2.6.0.

This command:

- Calls the drop_deployment command

Note

While running it may ask for the remote server `root` password and the specified `db_user` password.

Note

This command is intended for removing Pootle deployments performed using the stage_feature command.

Warning

This command requires using the `staging` environment passing to it the `feature` argument and the desired branch.

Examples:

    $ fab staging:branch=feature/extension-actions,feature=yes unstage_feature

### update_code

This command:

- Updates the Pootle repository from GitHub
- Checks out the specified branch, using master if no branch is specified
- Updates the deployment requirements as listed in `requirements/`, including the base requirements as well

Note

Changed in version 2.5.1: Added support for updating code from a given branch on Pootle repository.

Examples:

    $ fab production update_code  # Call that will use the default 'master' branch
    $ fab production:branch=stable/2.5.0 update_code  # Call which provides a branch

### update_config

This command:

- Will upload the configuration files included in the chosen environment to the remote server:
  - Configure VirtualHost using the provided `virtualhost.conf`
  - Configure WSGI application using the provided `pootle.wsgi`
  - Configure and install custom settings for Pootle using the provided `settings.conf`

Note

While running it may ask for the remote server `root` password or the `sudo` password (standard password for the remote user configured in the environment).

Examples:

    $ fab production update_config

### update_db

This command:

- Runs updatedb and migrate to update the database schema to the latest version

Examples:

    $ fab production update_db

### upgrade

New in version 2.5.1.

This command:

- Runs upgrade to apply any special post-schema-upgrade actions (including changes needed for updated Translate Toolkit version). This would typically be performed after running the update_code command. If you haven’t just upgraded Pootle or the Translate Toolkit to a new release, this isn’t generally required, so there is no need to run it unless release notes or other instructions direct you to do so.

Examples:

    $ fab production upgrade