⚠️ Before proceeding, please take the provided installation code and commit it as-is to your own source control. As you make changes or customize it, please commit these to your repo as well. This will help keep track of customizations and updates.
ℹ️ You will likely want to use one of the Self-Managed Backends as the state storage for this installer. Please document this (in the repo your store this code, an internal wiki, etc) so that future updates will be straightforward for you and your colleagues.
This project contains a Pulumi project to provision and orchestrate the following components:
- API container
- Console container
- Migrations container
- (optional) Nginx container for Load Balancing and TLS termination
- This can be disabled with
pulumi config set disableNginxProxy true - If disabled, you must provide your own Load Balancing and TLS termination solution.
- This can be disabled with
- You must have a license key from your sales contact.
The following are requirements of this deployment option:
- Virtual machine or physical server with Docker Engine installed
- At least 2 CPU cores w/ 8 GB memory
- At least 20GB SSD storage space
- MySQL 8.0 database
- At least 20GB SSD storage space
- A databaser user that has the following grants:
GRANT ALL PRIVILEGES ON 'pulumi'.* TO 'pulumi'@'%'GRANT CREATE USER ON *.* TO 'pulumi'@'%' WITH GRANT OPTION
- Object storage (for example, Minio)
- At least 200GB SSD storage space
- Pulumi CLI
- CLI configuration
pulumi login --localpulumi stack init- ℹ️ Document the state location and passphrase for your stack in your internal documentation system or update this README to contain it.
- Service and registry configuration
pulumi config set licenseKey --secret {licenseKey}- (optional) - if you're pulling images from registry other than docker hub:
pulumi config set imageRegistryAddress {registry address}pulumi config set imageRegistryUsername {registry username}pulumi config set imageRegistryAccessToken --secret {registry access token}
pulumi config set imageTag {imageTag}- see https://hub.docker.com/orgs/pulumi for the available tags. Pick the latest tag in the form of
DATE-NUMBER-signed.
- see https://hub.docker.com/orgs/pulumi for the available tags. Pick the latest tag in the form of
- create the local directory for config file storage:
mkdir -p ~/pulumi-ee/data- or optionally, set a custom base path with:
pulumi config set dataPath {custom path}
pulumi config set localKeysValue --secret {local keys value}- ℹ️ this value is used as the backing encryption key for the default secrets provider (e.g. the Selfhosted Service). The value should be at least 32 random characters - e.g.
head -c 32 /dev/random | sha256sum | head -c 32 | pulumi config set localKeysValue --secret --
- ℹ️ this value is used as the backing encryption key for the default secrets provider (e.g. the Selfhosted Service). The value should be at least 32 random characters - e.g.
- Database configuration
pulumi config set dbHost {db host}- (optional) - if your database is listening on an alternative port
pulumi config set dbPort 3306
pulumi config set dbUsername {db username}pulumi config set dbUserPassword --secret {db password}⚠️ (optional) if you are running Selfhosted Pulumi across multiple servers for High Availability, themigrationscontainer must only run on one of the servers. You can disable themigrationscontainer on all other servers with the following config:pulumi config set disableDbMigrations true
- Object storage configuration
pulumi config set storageAccessKey {storage access key}pulumi config set storageSecretKey --secret {storage secret key}pulumi config set storageCheckpointBucket {storage checkpoint bucket}- e.g.
s3://pulumi-checkpoints?endpoint=192.168.1.47:9000&s3ForcePathStyle=true - Note: the
endpoint=IP:PORTands3ForcePathStyle=truequery parameters are required if using an S3 compatible API for object storage.
- e.g.
pulumi config set storagePolicyPackBucket {storage policypack bucket}- e.g.
s3://pulumi-policypacks?endpoint=192.168.1.47:9000&s3ForcePathStyle=true - Note: the
endpoint=IP:PORTands3ForcePathStyle=truequery parameters are required if using an S3 compatible API for object storage.
- e.g.
- Domain configuration
pulumi config set apiDomain {domain for api}pulumi config set consoleDomain {domain for console}
- Nginx proxy configuration
- (optional) - this can be handled via your own load balancing solution if you prefer
- to disable the nginx proxy and TLS termination:
pulumi config set disableNginxProxy true
- TLS Certification configuration
- ℹ️ skip this section if you have disabled the Nginx proxy or are handling this via an external load balancer or don't want to enable TLS
cat {path to api key file} | pulumi config set apiTlsKey --secret --(on a mac or linux machine)cat {path to api cert file} | pulumi config set apiTlsCert --secret --(on a mac or linux machine)cat {path to console key file} | pulumi config set consoleTlsKey --secret --(on a mac or linux machine)cat {path to console cert file} | pulumi config set consoleTlsCert --secret --(on a mac or linux machine)
- Miscellaneous configuration
- (optional) - expose the containers directly for troubleshooting purposes or for integrating with an external load balancer
pulumi config set exposeContainerPorts true
- (optional) - expose the containers directly for troubleshooting purposes or for integrating with an external load balancer
- SSO/SAML Configuration - once set email access is not available
pulumi config set samlSsoEnabled true
- SMTP Configuration - required for "reset password" and invite emails
pulumi config set smtpServer {smtp server}pulumi config set smtpUsername {smtp username}pulumi config set smtpPassword {smtp password} --secretpulumi config set smtpFromAddress {smtp from address}(email address that the outgoing emails come from)
- Recaptcha configuration - for protecting "forgot password" form
pulumi config set recaptchaSiteKey {recaptchaSiteKey}(this must be a v2 type recaptcha)pulumi config set recaptchaSecretKey {recaptchaSecretKey} --secret
pulumi up
Create DNS A record entries for {domain for api} and {domain for console} that point to the IP address of the virtual machine or physical server.
Login to your Self-Hosted Pulumi Service with the following command:
pulumi login {domain for api}
Or from the project directory:
pulumi login $(pulumi stack output apiEndpoint)
pulumi destroy
Note: Files in
~/pulumi-ee/data(or the path specified by thedataPathconfig value) will not be removed during thedestroy.
End users of the Pulumi Console must have network connectivity to the running API and Console containers via the included Nginx proxy or an external load balancer solution. CLI users require the same connectivity as well as connectivity to the object storage buckets specifically for publishing and using Policy Packs (via signed URLs).
New features and bugfixes are generally released on a weekly or bi-weekly schedule. They are released in the form of updated Docker images on https://hub.docker.com/orgs/pulumi.
To upgrade:
pulumi config set imageTag {imageTag}pulumi up
During the upgrade via pulumi up, the pulumi project will replace running Docker containers. There may be a brief interruption while the containers restart and the nginx load balancer configuration (if not disabled) is updated.
All application logs are written to stdout/stderr and available via docker logs. Centralized logging can be configured with additional logging drivers.
All state and data is stored in the external MySQL database and object storage. Data backups should be peformed on a regular schedule using the system-specific backup tooling.
The Selfhosted Pulumi can be run in a highly available configuration by running the configuration across multiple virtual machines or physical servers. When run in this configuration an external load balancer must be used to load balance and/or failover between the additional hosts.
⚠️ If you are running Selfhosted Pulumi across multiple servers for High Availability, themigrationscontainer must only run on one of the servers. You can disable themigrationscontainer with the following config for all other servers:
pulumi config set disableDbMigrations true
- The Pulumi project will create and write to multiple files in
~/pulumi-ee/data. These files should not be manually edited or deleted. This path can be customized with thedataPathstack configuration value. - The SSO certificate has the
currentYear()in the name. This means that it will get replaced during the first deployment of each calendar year. The expiry date on the certificate is set to 400 days so that although a deployment may not happen each year, it will be necessary to do so otherwise the certificate will expire.