Upsun User Documentation

Redirects

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!ยน A monthly $19 perk!
ยนTerms and conditions apply
Activate your 15-day trial

Managing redirection rules is a common requirement for web applications, especially in cases where you do not want to lose incoming links that have changed or been removed over time.

You can manage redirection rules on your Upsun projects in two different ways, which we describe here. If neither of these options satisfy your redirection needs, you can still implement redirects directly from within your application, which if implemented with the appropriate caching headers would be almost as efficient as using the configuration options provided by Upsun.

Whole-route redirects Anchor to this heading

Using whole-route redirects, you can define very basic routes in your .upsun/config.yaml file whose sole purpose is to redirect. A typical use case for this type of route is adding or removing a www. prefix to your domain, as the following example shows:

routes:
    https://{default}/:
        type: redirect
        to: https://www.{default}/

Partial redirects Anchor to this heading

In the .upsun/config.yaml file you can also add partial redirect rules to existing routes:

routes:
    https://{default}/:
        # ...
        redirects:
            expires: 1d
            paths:
                '/from':
                    to: 'https://example.com/'
                '^/foo/(.*)/bar':
                    to: 'https://example.com/$1'
                    regexp: true

This format is richer and works with any type of route, including routes served directly by the application.

Two keys are available under redirects:

Key Required Description
expires No The duration the redirect is cached. Examples of valid values include 3600s, 1d, 2w, 3m.
To disable caching for all your redirects, set expires to 0. You can also disable caching on a specific redirect.
paths Yes The paths to be redirected

Each rule under paths is defined by a key describing:

  • The expression to match against the request path
  • A value object describing both the destination to redirect to, with detail on how to handle the redirection

The value object is defined with the following keys:

Key Required Default Description
to Yes n/a A relative URL - '/destination', or absolute URL - 'https://example.com/'.
regexp No false Specifies whether the path key should be interpreted as a PCRE regular expression. If you use a capturing group, the replace field ($1) has to come after a slash (/). More information.
prefix No true, but not supported if regexp is true Specifies whether both the path and all its children or just the path itself should be redirected. More information.
append_suffix No true, but not supported if regexp is true or if prefix is false Determines if the suffix is carried over with the redirect. More information.
code No n/a HTTP status code. Valid status codes are 301, 302, 307, and 308. Defaults to 302. More information.
expires No Defaults to the expires value defined directly under the redirects key, but can be fine-tuned. To disable caching on a specific redirect, set expires to 0. The duration the redirect is cached for. More information.

To set up partial redirects, you can use regular expressions (regexp).
Alternatively, and in many cases, you can use the prefix and/or append_suffix keys to achieve the same results.
Here are some examples to illustrate this and help you choose a method for your partial redirects:

Consider this regexp redirect:

'^/from(/.*|)$':
    regexp: true
    to: https://example.com/to$1

It achieves the same result as this basic redirect:

'/from':
    to: https://example.com/to 

Consider this redirect using prefix:

'/from':
    to: https//example.com/to
    prefix: false

It achieves the same result as this regexp redirect:

'^/from$':
    regexp: true
    to: https://example.com/to

Consider this redirect using append_suffix:

'/from':
    to: https//example.com/to
    append_suffix: false

It achieves the same result as this regexp redirect:

'^/from(/.*|)$':
    regexp: true
    to: https://example.com/to

Redirects using regular expressions Anchor to this heading

You can use regular expressions to configure your redirects.

In the following example, a request to https://example.com/foo/a/b/c/bar redirects to https://example.com/a/b/c:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            paths:
                '^/foo/(.*)/bar':
                    to: 'https://example.com/$1'
                    regexp: true

The following special arguments in the to statement are available when regexp is set to true:

  • $is_args evaluates to ? or empty string
  • $args evaluates to the full query string if any
  • $arg_foo evaluates to the value of the query parameter foo
  • $uri evaluates to the full URI of the request.

Redirects using prefix and append_suffix Anchor to this heading

Instead of using regular expressions to configure your redirects, you might want to use the prefix and append_suffix keys.

When set to true, which is their default value, prefix and append_suffix are equivalent. For example:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            paths:
                '/from':
                    to: 'https://{default}/to'
                    prefix: true
routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            paths:
                '/from':
                    to: 'https://{default}/to'
                    append_suffix: true

With both configurations:

  • /from redirects to /to
  • /from/some/path redirects to /to/some/path

However, when set to false, prefix and append_suffix behave differently. For example, with the following configuration:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            paths:
                '/from':
                    to: 'https://{default}/to'
                    prefix: true

A request to /from/ redirects to /to/some/path, but a request to /from/some/path does not.

And with the following configuration:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            paths:
                '/from':
                    to: 'https://{default}/to'
                    append_suffix: false

A request to /from/some/path (and any path after /from) redirects to just /to.

Specify a HTTP status code Anchor to this heading

To set a specific HTTP status code for your redirect, use the codes key:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            paths:
                '/from':
                    to: 'https://example.com/'
                    code: 308
                '/here':
                    to: 'https://example.com/there'

In this example, redirects from /from use a 308 HTTP status code, while redirects from /here default to 302 (“found”, as long as the resource is indeed found as a result from the redirect).

Manage caching Anchor to this heading

You can set an expiration time on your redirects or even disable caching on them.

Set an expiration time on your redirects Anchor to this heading

You can specify how long you want your redirects to be cached for. To do so, use the expires key under the redirects key.

In the following example, all redirects are cached for two weeks:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            expires: 2w
            paths:
                '/from':
                    to: 'https://example.com/'
                '/here':
                    to: 'https://example.com/there'

If you want to set a different expiration time for a specific redirect, use the same expires key, but under the paths key.

In the following example:

  • The first redirect uses the default expiration time set on all redirects and is cached for two weeks
  • The second redirect ignores the default expiration time set on all redirects, and is cached for three days instead
routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            expires: 2w
            paths:
                '/from':
                    to: 'https://example.com/'
                '/here':
                    to: 'https://example.com/there'
                    expires: 3d

Disable caching on your redirects Anchor to this heading

To disable caching on all your redirects, set the expires key to 0 under the redirects key:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            expires: 0
            paths:
                '/from':
                    to: 'https://example.com/'
                '/here':
                    to: 'https://example.com/there'

To disable caching on a specific redirect only, set the expires key to 0 under the relevant path in the paths section.

In the following example, caching is disabled on the second redirect only:

routes:
    https://{default}/:
        type: upstream
        # ...
        redirects:
            paths:
                '/from':
                    to: 'https://example.com/'
                '/here':
                    to: 'https://example.com/there'
                    expires: 0

Other redirects Anchor to this heading

Application-driven redirects Anchor to this heading

If neither whole-route or partial redirects satisfy your redirection needs, you can still implement redirects directly in your application. If sent with the appropriate caching headers, this is nearly as efficient as implementing the redirect through one of the two configurations described above. Implementing application-driven redirects depends on your own code or framework and is beyond the scope of this documentation.

Query-strings based redirects Anchor to this heading

Upsun does not support redirects based on query strings.

If you want to redirect based on query strings, this logic has to be implemented by your application.

Is this page helpful?