Outline Server Documentation

Outline Server provides Shadowsocks services and a service management API. It consists of two primary components:

• Outline Server (Shadowbox): The core proxy server located in src/shadowbox. It manages outline-ss-server (a Shadowsocks backend) and provides a REST API for managing access keys.
• Metrics Server: A REST service located in src/metrics_server used for optional, anonymous metrics sharing.

The Outline Shellcheck Wrapper is used to lint scripts within the repository using a pinned version of Shellcheck. The wrapper automates the following process:

1. Identifies the developer's operating system (Linux, macOS, or Windows).
2. Downloads the specific pinned version of Shellcheck into the ./download directory.
3. Verifies the archive hash for security.
4. Extracts and runs the executable.

The executable is cached locally after the initial download to improve performance.

Use the provided task command to build the Outline Sentry webhook project.

task sentry_webhook:build

To deploy the Outline Server manually, ensure you meet the prerequisites and follow these steps:

Prerequisites

• Node LTS (e.g., lts/hydrogen, version 18.16.0)
• NPM (version 9.5.1)
• Go (version 1.21 or higher)

Installation Steps

1. Install project dependencies:

   npm install

2. Start the server using the task runner:

   ./task shadowbox:start

3. To clean up the environment:

   ./task clean

For detailed configuration and usage options, refer to the core server's documentation in src/shadowbox/README.md.

To perform a self-hosted installation, run the official installation script using wget. You can optionally customize the installation by providing flags such as --hostname and --keys-port.

# Standard installation
sudo bash -c "$(wget -qO- https://raw.githubusercontent.com/OutlineFoundation/outline-apps/master/server_manager/install_scripts/install_server.sh)"

# Customized installation
sudo bash -c "$(wget -qO- https://raw.githubusercontent.com/OutlineFoundation/outline-apps/master/server_manager/install_scripts/install_server.sh)" install_server.sh \
  --hostname=myserver.com \
  --keys-port=443

To route Sentry events to Salesforce via the webhook, you must configure each Outline Sentry project individually. Follow these steps for each project (e.g., outline-client, outline-client-dev, outline-server, outline-server-dev):

1. Log in to the Outline Sentry account.
2. Select the specific project you wish to configure.
3. Enable the WebHooks plugin at: https://sentry.io/settings/outlinevpn/<project>/plugins/
4. Set the webhook endpoint at: https://sentry.io/settings/outlinevpn/<project>/plugins/webhooks/
5. Configure alerts to invoke the webhook at: https://sentry.io/settings/outlinevpn/<project>/alerts/
6. Create rules to trigger the webhook at: https://sentry.io/settings/outlinevpn/<project>/alerts/rules/

The Outline Sentry webhook is a Google Cloud Run function. To deploy it, you must first authenticate with the Google Cloud SDK (gcloud) and then run the deploy task.

Requirements:

• Google Cloud SDK installed.
• Access to Outline's Sentry account.

gcloud auth login
task sentry_webhook:deploy

To build the Outline Server image and run the full integration test suite, use the shadowbox:integration_test task.

If you are developing the tests or want to test a specific image without rebuilding it first, you can call the test command directly by providing the IMAGE_NAME environment variable.

Deployment requires the Google Cloud SDK.

1. Authenticate with gcloud using gcloud auth login.
2. Deploy to the development environment using task metrics_server:deploy:dev.
3. Deploy to the production environment using task metrics_server:deploy:prod.

Note: After deployment, you must manually migrate all traffic to the new version via the Google Cloud console.