|
| 1 | +## Installing Private Packagist Self-Hosted with an embeded Kubernetes cluster |
| 2 | +## |
| 3 | + |
| 4 | +Private Packagist Self-Hosted leverages the [kots](https://docs.replicated.com/reference/kots-cli-getting-started) |
| 5 | +kubectl plugin by Replicated to run on a Kubernetes cluster. The plugin provides a management interface to your |
| 6 | +Private Packagist Self-Hosted installation and allows you to monitor the application and perform maintenance operations |
| 7 | +such as backups or updates. |
| 8 | + |
| 9 | +This page will guide you through an installation without an existing cluster. To instead install Private Packagist Self-Hosted |
| 10 | +in an existing Kubernetes cluster follow [this guide](./kubernetes-existing.md). |
| 11 | + |
| 12 | +## General requirements |
| 13 | + |
| 14 | +1. License Key File (file extension .yaml) Don't have one yet? [Sign up for a free trial license!](https://packagist.com/self-hosted) |
| 15 | +1. One (sub-)domain to operate the web interface, e.g. packagist.myintranet.com |
| 16 | +1. One (sub-)domain to operate the composer repository, e.g. repo.packagist.myintranet.com or packagist-repo.myintranet.com |
| 17 | +1. An SSL certificate valid for both chosen domains or use Let's Encrypt to generate a certificate for you |
| 18 | +1. An SMTP server or a GMail account for Private Packagist Self-Hosted to send email |
| 19 | +1. A Linux Server |
| 20 | + * A [supported operating system](https://kurl.sh/docs/install-with-kurl/system-requirements#supported-operating-systems) |
| 21 | + * At least 8GB memory |
| 22 | + * At least 4 CPU cores |
| 23 | + * At least 80GB disk space (or 40GB of disk space if a hosted Redis, PostgreSQL, and blob storage are used) |
| 24 | + * Ports 80, 443, and 8800 must be accessible, for a full list of ports |
| 25 | + * Must be reachable at the chosen domain names from your local machine |
| 26 | +1. If your firewall restricts external connections the following domains must be accessible from the server: |
| 27 | + * hub.docker.com |
| 28 | + * proxy.replicated.com |
| 29 | + * replicated.app |
| 30 | + * amazonaws.com |
| 31 | + * k8s.gcr.io |
| 32 | + * k8s.kurl.sh (required to install the kots CLI) |
| 33 | + * kots.io (required to install the kots CLI) |
| 34 | + * github.com (required to install the kots CLI) |
| 35 | +<!-- See https://docs.replicated.com/enterprise/installing-general-requirements and https://kurl.sh/docs/install-with-kurl/system-requirements --> |
| 36 | + |
| 37 | +## Installation |
| 38 | + |
| 39 | +To install Private Packagist Self-Hosted and Replicated run the command below. |
| 40 | +To learn more about options for the easy install script, please refer to the [Replicated manual on Installing Replicated](https://help.replicated.com/docs/kubernetes/customer-installations/installing/). |
| 41 | +``` |
| 42 | +curl -sSL https://kurl.sh/privatepackagistkots | sudo bash |
| 43 | +``` |
| 44 | + |
| 45 | +To log in to the admin console, you will need the password shown at the end of the install command. You can also always |
| 46 | +regenerate the admin console password via `sudo kubectl kots reset-password privatepackagistkots`. |
| 47 | + |
| 48 | +After your Replicated Kubernetes cluster is up and running you can follow the rest of the Packagist guide. |
| 49 | + |
| 50 | +### Replicated Configuration |
| 51 | +#### Replicated Setup |
| 52 | +Once Replicated’s services are installed on your server you need to access the management console on your browser. |
| 53 | +It’s available via SSL on port 8800. Open https://packagist.myintranet.com:8800/ in your browser (replace the domain with your own). |
| 54 | +You will have to proceed despite the security warning (since your certificate is still missing). |
| 55 | + |
| 56 | + |
| 57 | + |
| 58 | +Upload your SSL certificate on the next screen. SSL should work correctly from the next page. |
| 59 | +If your certificate requires intermediate certificates to be recognized by your browser and/or Composer, |
| 60 | +you can paste them into the certificate file together with your own certificate. |
| 61 | +Make sure your own certificate comes first, any intermediate certificate next and the root certificate last. |
| 62 | +If the order is off replicated will not recognize your certificate at all. |
| 63 | + |
| 64 | +If instead you would like to use Let's Encrypt to automatically generate a certificate for Private Packagist then you can |
| 65 | +continue with the self-signed certificate for now. Please note that the Let's Encrypt certificate won't be used for the |
| 66 | +admin console. |
| 67 | + |
| 68 | + |
| 69 | + |
| 70 | +Login to the admin console using the password generated during the kots application installation. |
| 71 | + |
| 72 | + |
| 73 | + |
| 74 | +On the next screen, you can upload the supplied .yaml license key file. If you don't have the license key file yet then |
| 75 | +you can download it from https://packagist.com. |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +#### Configure Private Packagist Self-Hosted |
| 80 | +The configuration screen is where you can set up the domains used for Private Packagist and the email configuration. It |
| 81 | +is also the place where you can configure if Private Packagist should use an existing Redis, PostgreSQL, or blob storage. |
| 82 | + |
| 83 | + |
| 84 | +Every configuration change or application update will trigger a preflight check. Once the preflight check have passed, |
| 85 | +the changes can be applied to your Kubernetes cluster. |
| 86 | + |
| 87 | + |
| 88 | +The application overview in the admin console shows you the application status, your current license information, and any |
| 89 | +available updates for Private Packagist. Once the application has entered the ready state, you can access Private Packagist |
| 90 | +via the domain configured for the web interface e.g. packagist.myintranet.com and finish the setup there. |
| 91 | + |
| 92 | + |
| 93 | +### Setup authenticateion and Select Admin |
| 94 | + |
| 95 | +#### Authentication Setup |
| 96 | +Within Private Packagist Self-Hosted, you now need to set up at least one user authentication method. |
| 97 | +You have the choice between authentication with email addresses and passwords and several OAuth integrations with third-party services. |
| 98 | +We provide integrations with on-premises versions of GitHub, Bitbucket, GitLab, or their public services on github.com, bitbucket.org, |
| 99 | +or gitlab.com. Follow the instructions to create the respective required identifiers, tokens, and secrets. |
| 100 | + |
| 101 | +* [GitHub (Enterprise) Integration Setup](./github-integration-setup.md) |
| 102 | +* [Bitbucket.org Integration Setup](./bitbucket-integration-setup.md) |
| 103 | +* [Bitbucket Data Center / Server Integration Setup](./bitbucket-server-integration-setup.md) |
| 104 | +* [GitLab Integration Setup](./gitlab-integration-setup.md) |
| 105 | +* [Authentication with Email Addresses and Passwords](./authentication-email-addresses-passwords-setup.md). |
| 106 | + |
| 107 | + |
| 108 | + |
| 109 | + |
| 110 | +#### Selecting Admins |
| 111 | +After setting up an integration, you can log in through the top menu. Register an account and pick a username. |
| 112 | + |
| 113 | + |
| 114 | + |
| 115 | +The first user is granted admin permissions automatically. You can grant admin permissions to more users in the admin panel. |
| 116 | + |
| 117 | + |
| 118 | + |
| 119 | +#### Switching to Production Mode |
| 120 | +Head back to the admin console to disable the Setup Mode in the configuration. Once the preflight checks passed, you can |
| 121 | +apply the changes. |
| 122 | + |
| 123 | +That’s it! Private Packagist Self-Hosted is now ready to be used! You’ll find all further information in the web interface. |
| 124 | + |
| 125 | +## Database and storage |
| 126 | + |
| 127 | +Private Packagist Self-Hosted will set up PostgreSQL, Redis, and MinIO to store application data and Composer packages. |
| 128 | +Each of them requires one or more volumes if you prefer to avoid that then you can configure to use your own PostgreSQL, |
| 129 | +Redis, and blob storage. For blob storage, we currently support Azure Blob Storage, Google Cloud Storage, AWS S3, and |
| 130 | +other S3-compatible storage solutions. |
| 131 | + |
| 132 | +Please note that the backup solution provided only covers the built-in services and you are responsible for creating backups |
| 133 | +of any services that you run yourself. |
| 134 | + |
| 135 | +## Backups |
| 136 | + |
| 137 | +The Replicated Admin console integrates with [Velero](https://velero.io/), a tool to back up and restore your Kubernetes |
| 138 | +cluster resources and persistent volumes. It is automatically installed with an embedded cluster installation. |
| 139 | + |
| 140 | +Once your Private Packagist Self-Hosted is up and running, you can configure the storage destination and the backup |
| 141 | +schedule in the Replicated Admin console under Snapshot settings. We recommend using an external storage solution like |
| 142 | +Amazon S3 and configuring full snapshots. |
| 143 | + |
| 144 | +To restore Private Packagist Self-Hosted from a snapshot, access the "Full Snapshots" and click on the "Restore from backup" |
| 145 | +icon. You will then see information on how to either perform a full restore or only restore the Private Packagist Self-Hosted |
| 146 | +application. During the restore process both Private Packagist Self-Hosted and the Replicated Admin console will become |
| 147 | +unavailable. |
0 commit comments