server

Definition

The server command allows you to manage the Fugue API server. Currently, there is one subcommand: run.

Before you can access the server command, you must export an environment variable:

export FUGUE_BETA_API=true

Usage

fugue server [OPTIONS] COMMAND [ARGS]...

Subcommands

run
Run the API server.

Options

Global options are detailed here.

h | --help
Show help text. The help flag is available throughout the CLI in both an application-level and command-level context. It enables a user to view help text for any command within the Fugue CLI.

Server Subcommands

run

Definition

fugue server run launches an API server. Once the server is up, you may send it API requests corresponding to Fugue commands, and you’ll generally receive JSON responses. (Certain calls return a 204 No Content message, and others return an x-tar response. See the Fugue API Reference for details.)

By default, the server listens on port 8080. You can configure the port by using the --port <port> option.

By default, the server runs without a credentials profile, so authentication is provided by the client. Your Fugue user (RBAC) credentials must be included in every HTTP request header, using Basic Authentication. (Note: Your Fugue user credentials are not your AWS credentials. Fugue user credentials are composed of a user and secret corresponding to a profile stored in a credentials file. AWS credentials are composed of an access key ID and secret access key corresponding to an AWS account.)

You can specify a profile for the API server to use by setting the --profile <profile> option. This means you don’t need to include credentials in request headers (and, in fact, they are ignored). The <profile> name must match a profile in your Fugue credentials file, which is typically located in the same directory as your fugue.yaml file, but Fugue also looks for it in the locations listed here.

For more details, see Fugue REST API or Managing Processes with the Fugue API.

Usage

fugue server run [options]

Options

--port <port>
The port number to listen for connections on. Default: 8080
--profile <profile>
The name of the Fugue profile to use.
-h | --help
Show help text.

Examples

Starting the Fugue API server

To start up the Fugue API server, execute the following command:

fugue server run

You’ll see output like this:

Fugue server starting on port 8080

fugue server run blocks at the command line, so if you want to run it in the background, use this command:

fugue server run &

Stopping the Fugue API server

To stop the Fugue API server, simply press <CTRL+C>.

If the server is running in the background, you can execute the following command to locate the process ID, or PID:

ps | grep fugue

Then terminate the server with the following command, substituting <PID> for your actual PID:

kill <PID>

Specifying the API server’s port

To have the Fugue API server listen on a port other than 8080 (default), use the --port <port> option. This example uses port 4000:

fugue server run --port 4000

You’ll see output like this:

Fugue server starting on port 4000

Running the server with a Fugue user profile

By default, the fugue server run command requires authentication to be sent by the client. Every HTTP request made to the server must include Fugue credentials (not AWS credentials) in the header, using Basic Authentication.

However, if you use --profile <profile> to run the server with a Fugue user profile, there’s no need to include credentials in request headers. In fact, when a server runs with a profile, all authentication passed in HTTP headers is ignored. API requests are granted or denied according to the permissions granted for that user in the Conductor’s RBAC policy, and server permissions cannot be overridden by sending different credentials in request headers.

The <profile> name must match a profile in your Fugue credentials file. Example Fugue user credentials:

[default-123456789012-us-east-1]
user = root
secret = gIowKW6AnAM4fgBqEXAMPLEEXAMPLEEXAMPLEEXAMPLE=

Above, default-123456789012-us-east-1 is the profile name. The user root and secret gIowKW6AnAM4fgBqEXAMPLEEXAMPLEEXAMPLEEXAMPLE= comprise the Fugue user credentials.

To launch the API server using the above profile, execute the following command:

fugue server run --profile default-123456789012-us-east-1

The credentials file is typically located in the same directory as your fugue.yaml file, but Fugue also looks for it in the locations listed here.

Profiles and authentication

Because the API server uses Fugue user credentials for authentication, you may only send API requests corresponding to that user’s permissions as defined in the RBAC policy. All other requests will return an error. (Your default profile is named default-<AWS account number>-<region> and has the default Fugue user root, which has access to all actions.)

Likewise, if you run the server without a profile and include Fugue user credentials in the request headers, you’ll only receive successful responses for the actions allowed for that user.