Merge pull request #106 from packagist/add-clear-redis-cache

SelfHosted: Explain how to clear Redis cache

Author: stevenrombauts

docs/self-hosted/kubernetes-maintenance.md

@@ -1,15 +1,26 @@
 # Maintenance
 ## Private Packagist Self-Hosted (Kubernetes)
 
+## kURL installations
+
 ### Updates
 
+This section describes how to update a Private Packagist Self-Hosted in a Kubernetes cluster installed with [kURL](kubernetes-embedded).
+This section is not relevant if you installed the application with [Helm](kubernetes-helm).
+
 By default Replicated checks for updates every 4 hours and you can install updates from the dashboard in the Replicated
 Management Console on port 8800 once they are available.
 You can configure this behavior under “Configure automatic updates” on the dashboard.
 
 The [Private Packagist Self-Hosted Changelog](https://packagist.com/docs/self-hosted/changelog) details all new features,
 behavior changes and major bugfixes each release introduces.
 
+You can safely bump multiple versions at once, it's not required to install individual versions consecutively. If we ever 
+release a version that needs to be installed specifically, we will make sure to communicate this first.
+
+We recommend backing up your database before each update. We cannot guarantee that downgrading to a previous release will always work
+due to database migrations. In case of upgrade failure, the most reliable way to rollback to the previous version is via a snapshot.
+
 New versions that ask you to upgrade KOTS (Kubernetes Off-The-Shelf), the Replicated tool used to distribute Private Packagist,
 require that you download and rerun the install script via the command below.
 
@@ -22,19 +33,27 @@ Private Packagist and the Replicated Management Console will become temporarily
 curl -sSL https://k8s.kurl.sh/privatepackagistkots | bash -s
 ```
 
-#### Update KOTS for Private Packagist Self-Hosted Kubernetes in an existing cluster
+### Update or replace the SSL certificate
 
-```
-curl https://kots.io/install | bash
-kubectl kots admin-console upgrade -n NAMESPACE
-```
+To update or replace the certificate, you must first restore the ability to upload new TLS certificates and then reupload
+the certificate through the user interface. Please refer to the
+[Replicated documentation](https://docs.replicated.com/enterprise/updating-tls-cert#update-custom-tls-certificates)
+for detailed instructions.
 
-Replace `NAMESPACE` with the namespace in your cluster where KOTS is installed.
+## Helm installations
 
-### Update or replace the SSL certificate
+### Updates
 
-To update or replace the certificate, you must first restore the ability to upload new TLS certificates and then reupload 
-the certificate through the user interface. Please refer to the 
-[Replicated documentation](https://docs.replicated.com/enterprise/updating-tls-cert#update-custom-tls-certificates) 
-for detailed instructions.
+If you installed Private Packagist Self-Hosted with Helm into your existing cluster, you can update the application with the command 
+below. Make sure to compare your existing `values.yaml` file to the [current one](http://packagist.com.lo/docs/self-hosted/kubernetes-helm#annotated-configuration) first.
+
+``` 
+helm upgrade -f values.yaml private-packagist oci://registry.replicated.com/privatepackagistkots/private-packagist --version VERSION
+```
+
+You can find the latest version in the [changelog](changelog). You can safely bump multiple versions at once, it's not required to
+install individual versions consecutively. If we ever release a version that needs to be installed specifically, 
+we will make sure to communicate this first. 
 
+We recommend backing up your database before each update. We cannot guarantee that downgrading to a previous release will always work 
+due to database migrations. In case of upgrade failure, the most reliable way to rollback to the previous version is via backup.

docs/self-hosted/kubernetes-migration-guide.md

@@ -188,3 +188,24 @@ Ideally, run a `composer update` command in one of your projects to assert that
 
 In case you initially set up Private Packagist Self-Hosted Kubernetes with a different domain name, you can now edit the
 domain names in the admin panel. If necessary, adjust your DNS entries, and shut down the old Private Packagist Self-Hosted instance.
+
+### Clear the cache
+
+The final step is to clear the Composer endpoint cache. If you are not using the built-in Redis database, check your internal documentation how to connect to the Redis instance.
+
+**Important:** Please note that there are multiple databases created in your Redis instance, and that Redis is not solely used for caching.
+Be careful not to flush any of the other migrated databases.
+
+```
+kubectl exec -it redis-0 -- redis-cli -p 9869 
+select 5
+flushdb
+```
+
+### Update Composer projects
+
+Update the Composer projects that use your self-hosted Private Packagist instance to make sure all repository references are up-to-date:
+
+```
+composer update mirrors
+```

docs/self-hosted/kubernetes-troubleshooting.md

@@ -60,4 +60,21 @@ proxy_ssl_server_name on;
 If you are using different hostnames on the upstream and on the reverse-proxy, set the value in the
 `proxy_ssl_name` directive to the corresponding hostname of the upstream server.
 
+#### Issues after changing the Private Packagist Self-Hosted domain name
+
+If you've changed the domain name used to access your Private Packagist Self-Hosted Kubernetes installation, you'll need to clear the Composer endpoint Redis cache.
+
+**Important:** Please note that there are multiple databases created in your Redis instance, and that Redis is not solely used for caching.
+Be careful not to flush any of the other databases.
+
+If you are not using the built-in Redis database, check your internal documentation how to connect to the Redis instance.
+
+```
+kubectl exec -it redis-0 -- redis-cli -p 9869
+select 5
+flushdb
+```
+
+Afterwards, run `composer update mirrors` to make sure all repository references are up-to-date. 
+