Command Line Interface

Overview

Smeagol provided multiple binaries ot make it easy to use:

• smeagol - The main executable simply dispatches to the others sub-executables.
• smeagol-preview - Preview the wiki at the current working directory.
• smeagol-serve - Serve all configured repositories.
• smeagol-update - Run a git pull update on configured repositories.
• smeagold - A command for daemonizing the Smeagol server.*

If you are setting up or testing a Smeagol installation, start by using the smeagol-preview command. It allows you to start and stop your server quickly and allows you to see logging information in your console. Once your server is setup, use the smeagol-serve or smeagold commands to run your server as a background process.

• NOTE: As of v0.6.0, we have had issues with getting smeagold to run. Hopefully these will be fixed soon, though we may deprecate it instead, since most hosting providers have other means of handling daemonization.

Options

The following command line options are available for smeagol-serve and smeagold:

• --port or -p - The port to run the server on. (Default 4567)
• --config or -c - The path to the configuration file. When specified, the global configuration is ignored.
• --auto-update - Automatically updates the Gollum repository once per day.
• --no-cache - Turns off page caching.
• --secret - Sets the update authorization key for all repositories.

The last parameter in the command is the path to the Gollum repository. If omitted and no repositories are specified in the configuration file, the current directory is used.

Environment Variables

• git - The path to the local git binary. If not specified, it is assumed that git is command and it is in PATH. NOTE: This should no longer apply, as the Grit library is now being used for all git commands. However there may a case or two not yet refactored. Please report an issue if it comes up.

Configuration File

All the command line options can be specified in a configuration file. The configuration file is in YAML format and most command line options are available in the configuration file. If no configuration file is specified on the command line, the global configuration file at /etc/smeagol/config.yml will be used.

The options are:

• port - The bind port.
• auto_update - A flag stating if auto update is enabled. Either true or false.
• cache_enabled - A flag stating if page caching is enabled. Either true or false.
• repositories - An array of repository objects. Each repository has three settings: path, cname and secret.

Below is an example configuration file:

port: 80
git: /root/git
auto_update: true
cache_enabled: true

repositories:
  - path: /root/wikis/my_wiki
    cname: mycoolwiki.com
    secret: dont-tell-anyone
  - path: /root/wikis/my_other_wiki
    cname: wiki.example.com

Multiple Repository Support

As shown in the YAML example above, multiple repositories can be served by the same Smeagol instance. This is done by specifying the CNAME attribute for the domain or subdomain that the wiki will be served from.

The first wiki specified in the configuration file or the command line repository (if specified) is the default repository. If a page is served from an unspecified domain then the default repository will be used.

Secret Update Authorization Key

Smeagol has a simple mechanism for preventing other people from updating your repository. By specifying the secret property on a repository, you will only be able to update your repository by passing that secret to your update request like this:

http://hostname/update/this_is_my_secret

Assuming you have set your secret as this_is_my_secret in your configuration file or on the command line, your repository will be updated. Otherwise, Smeagol will let you know that you cannot perform an update.

Daemonize

To daemonize the Smeagol server, use the smeagold command. The smeagold command accepts the following commands:

• start - Starts the server.
• stop - Stops the already running server.
• restart - Restarts the server.
• run - Runs the server without daemonizing it. This is useful for testing the smeagold command.

To pass command line arguments to your server, specify them after double dashes (--) like this:

$ smeagold start -- -p 80 /path/to/repo