import { TabsGroup, TabsItem } from "@/components/DocsTabs";
import Alert from "@/components/DocsAlert";
import Image from "next/image";

# Upgrade Firezone

Upgrading Firezone will pause all VPN sessions and temporarily bring down the
web UI.

<Alert
  color="info"
  html={`
Automatic rollbacks are still under development. We recommend backing up
relevant <a href="/docs/reference/file-and-directory-locations">files and folders</a>
before upgrading in case anything goes wrong.
`}
/>

Follow the steps below to upgrade Firezone:

<TabsGroup>
<TabsItem title="Docker" active>

1. Change to your Firezone installation directory, by default `$HOME/.firezone`:

```
cd $HOME/.firezone
```

1. If your `.env` file has a `VERSION` variable, update it to the desired
   version. By default `latest` is assumed if not set. This variable is read in
   newer versions of the docker-compose.yml template to populate the `image:`
   key for the `firezone` service.
1. Update service images:

```
docker compose pull
```

1. Re-up the services (**warning: this will restart updated services**):

```
docker compose up -d
```

</TabsItem>
<TabsItem title="Omnibus">

1. If not setup already, install our package repository based on your distro's
   package format:

- [deb packages](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-deb)
- [rpm packages](https://cloudsmith.io/~firezone/repos/firezone/setup/#formats-rpm)

1. Upgrade the `firezone` package using your distro's package manager.
1. Run `firezone-ctl reconfigure` to pick up the new changes.
1. Run `firezone-ctl restart` to restart services.

</TabsItem>
</TabsGroup>

If you hit any issues, please let us know by
[filing an issue](https://github.com/firezone/firezone/issues/new/choose).

## Upgrading to 0.7.x

Firezone 0.7.0 introduces a new [REST API](/docs/reference/rest-api) that allows
administrators to automate much of the day to day configuration of Firezone.

The REST API `/v0/configuration` endpoint supersedes some of the previous
environment variables used for WireGuard server configuration.

If you're running Firezone &lt; 0.6, we recommend updating to the latest 0.6.x
release **before** upgrading to 0.7. This will ensure any environment variables
are properly parsed and migrated into the DB as runtime `configurations`.

**Note**: Omnibus deployments are deprecated in 0.7.x and will be removed in
Firezone 0.8 and above. We recommend
[migrating your installation](/docs/administer/migrate) to Docker if you haven't
done so already.

## Upgrading to >= 0.6.12

### WIREGUARD\_\* env vars

Firezone 0.6.12 moves the `WIREGUARD_ALLOWED_IPS`,
`WIREGUARD_PERSISTENT_KEEPALIVE`, and `WIREGUARD_DNS` environment variables to
the database to be configured in the UI at `/settings/client_defaults`. If the
corresponding value at `/settings/client_defaults` was empty, the environment
variable's value was used to populate the field.

This is a small step in our quest to move more runtime configuration from
environment variables to the DB.

### `AUTH_OIDC_JSON` config

Similar to the `WIREGUARD_*` env vars above, the `AUTH_OIDC_JSON` env var has
similarly been moved to the database and can be configured at `/settings/site`.
In Firezone 0.7 this is now configurable via the
[REST API](/docs/reference/rest-api/configurations) as well.

### Fix IPv6

0.6.12 fixes IPv6 routing within Docker networks. To enable, add IPv6 addresses
to your `$HOME/.firezone/docker-compose.yml` by setting the following fields:

```yaml
services:
  firezone:
    networks:
      firezone-network:
        ipv6_address: fcff:3990:3990::99

# ...
networks:
  firezone-network:
    ipam:
      config:
        - subnet: fcff:3990:3990::/64
        - gateway: fcff:3990:3990::1
```

You also need to update the Docker daemon to enable IPv6. See our
[IPv6 guide](/docs/deploy/docker/#step-4-enable-ipv6-optional) for more info.

## Upgrading from 0.5.x to 0.6.x

Firezone 0.6 introduces **Docker support**, SAML 2.0 authentication, more
granular user provisioning options, and a slew of minor improvements and
bugfixes.

### Migrate to Docker

Docker is now the preferred way to deploy and manage Firezone. See the
[migration guide](/docs/administer/migrate) to migrate today. In most cases this
can be done in a few minutes using our automatic migration script.

### Update Configuration

Some configuration variables have recently moved to the DB in order to be
configurable at runtime. Check the [configure guide](/docs/deploy/configure) for
more information.

## Upgrading from < 0.5.0 to >= 0.5.0

0.5.0 introduces a few breaking changes and configuration updates that will need
to be addressed. Read more below.

### Bundled Nginx non_ssl_port (HTTP) requests removed

0.5.0 and above removes the `force_ssl` and `non_ssl_port` settings for Nginx.
SSL is required for Firezone to function; if you're using (or would like to use)
your own reverse proxy, we recommend disabling the bundle Nginx service by
setting `default['firezone']['nginx']['enabled'] = false` and pointing your
reverse proxy directly to the Phoenix app on port 13000 (by default).

Read more about setting up a custom reverse proxy
[here](/docs/deploy/advanced/reverse-proxy).

### ACME protocol support

0.5.0 introduces ACME protocol support for automatically renewing SSL
certificates with the bundled Nginx service. To enable,

- Make sure `default['firezone']['external_url']` contains a valid FQDN that
  resolves to your server's public IP address.

- Ensure port `80/tcp` is reachable

- Enable ACME protocol support with
  `default['firezone']['ssl']['acme']['enabled'] = true` in your config file.

### Overlapping egress rule destinations

Firezone 0.5.0 removes the ability to add rules with overlapping destinations.
When upgrading to 0.5.0, our migration script will automatically detect these
cases and **keep only the rules whose destination encompasses the other rule**.
If this is OK, **there is nothing you need to do**.

Otherwise, we recommend modifying your ruleset to eliminate these cases before
upgrading.

### Preconfigured Okta and Google SSO

Firezone 0.5.0 removes support for the old-style Okta and Google SSO
configuration in favor of the new, more flexible OIDC-based configuration. If
you have any configuration under the
`default['firezone']['authentication']['okta']` or
`default['firezone']['authentication']['google']` keys, **you need to migrate
these to our OIDC-based configuration using the guide below.**

#### Existing Google OAuth configuration

Remove these lines containing the old Google OAuth configs from your
configuration file located at `/etc/firezone/firezone.rb`

```ruby
default['firezone']['authentication']['google']['enabled']
default['firezone']['authentication']['google']['client_id']
default['firezone']['authentication']['google']['client_secret']
default['firezone']['authentication']['google']['redirect_uri']
```

Then, follow the instructions [here](/docs/authenticate/oidc/google) to
configure Google as an OIDC provider.

#### Existing Okta OAuth configuration

Remove these lines containing the old Okta OAuth configs from your configuration
file located at `/etc/firezone/firezone.rb`

```ruby
default['firezone']['authentication']['okta']['enabled']
default['firezone']['authentication']['okta']['client_id']
default['firezone']['authentication']['okta']['client_secret']
default['firezone']['authentication']['okta']['site']
```

Then, follow the instructions [here](/docs/authenticate/oidc/okta) to configure
Okta as an OIDC provider.

## Upgrading from 0.3.x to >= 0.3.16

Follow the instructions below based on your current version and setup:

### I have an existing OIDC integration

Upgrading to >= 0.3.16 requires the `offline_access` scope for some OIDC
providers to obtain a refresh token. This ensures Firezone syncs with the
identity provider and VPN access is terminated once the user is removed.
Previous versions of Firezone do not have this capability. Users who are removed
from your identity provider will still have active VPN sessions in some cases.

For OIDC providers that support the `offline_access` scope, you will need to add
`offline_access` to the `scope` parameter of your OIDC config. The Firezone
configuration file can be found at `/etc/firezone/firezone.rb` and requires
running `firezone-ctl reconfigure` to pick up the changes.

If Firezone is able to successfully retrieve the refresh token, you will see the
**OIDC Connections** heading in the user details page of the web UI for users
authenticated through your OIDC provider.

<Image
  className="mx-auto"
  alt="oidc connections"
  width={960}
  height={540}
  src="/images/oidc-connections.png"
/>

If this does not work, you will need to delete your existing OAuth app and
repeat the OIDC setup steps to
[create a new app integration](/docs/authenticate/oidc) .

### I have an existing OAuth integration

Prior to 0.3.11, Firezone used pre-configured OAuth2 providers. Follow the
instructions [here](/docs/authenticate/oidc) to migrate to OIDC.

### I have not integrated an identity provider

No action needed. You can follow the instructions
[here](/docs/authenticate/oidc) to enable SSO through an OIDC provider.

## Upgrading from 0.3.1 to >= 0.3.2

The configuration option `default['firezone']['fqdn']` has been removed in favor
of `default['firezone']['external_url']`. Please set this to the
publicly-accessible URL of your Firezone web portal. If left unspecified it will
default to `https://` + the FQDN of your server.

Reminder, the configuration file can be found at `/etc/firezone/firezone.rb`.
For an exhaustive list of configuration variables and their descriptions, see
the [configuration file reference](/docs/reference/configuration-file).

## Upgrading from 0.2.x to 0.3.x

Starting with version 0.3.0, Firezone no longer stores device private keys on
the Firezone server. Any existing devices should continue to function as-is, but
you will not be able to re-download or view these configurations in the Firezone
Web UI.

## Upgrading from 0.1.x to 0.2.x

Firezone 0.2.x contains some configuration file changes that will need to be
handled manually if you're upgrading from 0.1.x. Run the commands below as root
to perform the needed changes to your `/etc/firezone/firezone.rb` file.

```bash
cp /etc/firezone/firezone.rb /etc/firezone/firezone.rb.bak
sed -i "s/\['enable'\]/\['enabled'\]/" /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['enabled'] = true" >> /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['interval'] = 3_600" >> /etc/firezone/firezone.rb
firezone-ctl reconfigure
firezone-ctl restart
```
