diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..fa6d10fc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,16 @@ +# Documentation Guidelines + +## UI Label Formatting + +Use _italics_ for UI labels and navigation paths: +- Format: `_Settings > Manage Credentials_` +- Separator: `>` (not `->`) +- Examples: `_Add Package > By Url_`, `_Mirroring_`, `_Authentication Tokens_` + +Don't use backticks for UI labels - backticks are for code/commands only. + +## Links + +Do NOT include `.md` file extensions in links: +- ✅ `[Guide](mirror-magento-marketplace)` +- ❌ `[Guide](mirror-magento-marketplace.md)` diff --git a/docs/README.md b/docs/README.md index b444b966..367dad78 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ Alternatively you can copy the SSH public key for your organization on the same ### Add packages -If your organization is synchronized Private Packagist will have created packages for all of your private repositories containing a composer.json. Otherwise or if you would like to add additional packages you can add them in the _Packages_ section of your organization with the Add button. Follow the instructions to pick the right option for your package. +If your organization is synchronized Private Packagist will have created packages for all of your private repositories containing a composer.json. Otherwise or if you would like to add additional packages you can add them in the _Packages_ section of your organization with the _Add_ button. Follow the instructions to pick the right option for your package. ### Configure your project to use Private Packagist diff --git a/docs/centralized-authentication-and-sso.md b/docs/centralized-authentication-and-sso.md index da1db873..e6e65711 100644 --- a/docs/centralized-authentication-and-sso.md +++ b/docs/centralized-authentication-and-sso.md @@ -27,21 +27,21 @@ you can skip this step. Otherwise, the first step is making sure your users can OAuth authentication with the cloud versions of the default code hosting platforms (github.com, bitbucket.org and gitlab.com) is preconfigured on Private Packagist Cloud, but not on Private Packagist Self-Hosted. -Go to _Settings > Integrations_ and press the "Add Integration" button. +Go to _Settings > Integrations_ and press the _Add Integration_ button. ![Create an integration](/Resources/public/img/docs/articles/centralized-authentication-and-sso/configure-integration.png) ### 2 - Connect your account via OAuth -Go to your [profile](/profile) and find the _Connected Accounts_ section. Click on the "Connect" button to go through the OAuth authentication +Go to your [profile](/profile) and find the _Connected Accounts_ section. Click on the _Connect_ button to go through the OAuth authentication flow, and associate your Private Packagist account with your GitHub, GitLab or Bitbucket account. ![Connect your account via OAuth](/Resources/public/img/docs/articles/centralized-authentication-and-sso/profile-connect.png) ### 3 - Set up the synchronization -Now we can continue to set up the synchronization. In your organization, go to _Settings > Synchronizations_ and press the -"Add Synchronization" button. Follow the steps to complete the configuration. +Now we can continue to set up the synchronization. In your organization, go to _Settings > Synchronizations_ and press the +_Add Synchronization_ button. Follow the steps to complete the configuration. ![Create a synchronization](/Resources/public/img/docs/articles/centralized-authentication-and-sso/configure-synchronization.png) @@ -52,9 +52,9 @@ once they log in via OAuth. Only users who have logged into Private Packagist us Whether or not you are using automatic user provisioning, Private Packagist will always manage the same users as those provisioned in your code hosting platform. If a user is removed, that same user will also be removed from Private Packagist. -If you want to control which of your users should be allowed to access Private Packagist at all, you can opt to deactivate -users discovered by the synchronization by default. Then, only users that you activate manually will be able to log in. -To enable this behavior, go to the _Teams_ tab, and click on "View and manage all members of this organization" and check the box: +If you want to control which of your users should be allowed to access Private Packagist at all, you can opt to deactivate +users discovered by the synchronization by default. Then, only users that you activate manually will be able to log in. +To enable this behavior, go to the _Teams_ tab, and click on _View and manage all members of this organization_ and check the box: ![Deactivate users discovered by synchronization](/Resources/public/img/docs/articles/centralized-authentication-and-sso/deactivate-sync-members.png) @@ -64,20 +64,20 @@ Now we can enforce OAuth authentication for all users in the organization, to en identity system configured on the code hosting platform in order to access Private Packagist and cannot use an alternative method to log into Private Packagist. -Go to _Settings > Access_ and apply the changes. From now on, everyone - including yourself - will be required to +Go to _Settings > Access_ and apply the changes. From now on, everyone - including yourself - will be required to authenticate via your configured integration. ![Enforce OAuth authentication](/Resources/public/img/docs/articles/centralized-authentication-and-sso/enforce-oauth.png) ### 5 - Share the organization-specific login link -If you set up your own integration in Step 1, the final step is sharing your organization-specific login link with your users. -Look for the "Login link" button in _Settings > Integrations_ page. +If you set up your own integration in Step 1, the final step is sharing your organization-specific login link with your users. +Look for the _Login link_ button in _Settings > Integrations_ page. ![Login link settings](/Resources/public/img/docs/articles/centralized-authentication-and-sso/login-link-settings.png) This link presents the option to authenticate with your configured integration. Once the user clicks on the -"Log in with <integration name>" button, the authentication process is initiated and your users are redirected to your +_Log in with <integration name>_ button, the authentication process is initiated and your users are redirected to your code-hosting platform to log in. ![Login link example](/Resources/public/img/docs/articles/centralized-authentication-and-sso/login-link-example.png) diff --git a/docs/cloud/bitbucket-server-oauth1-integration-setup.md b/docs/cloud/bitbucket-server-oauth1-integration-setup.md index 22ba5d28..529df51a 100644 --- a/docs/cloud/bitbucket-server-oauth1-integration-setup.md +++ b/docs/cloud/bitbucket-server-oauth1-integration-setup.md @@ -26,8 +26,8 @@ To allow your users to authenticate to Private Packagist with their Bitbucket Da first need to create an integration in Private Packagist. This document walks you through the required steps. ## Open the Add Integration form -From the organization settings page, select the "Integrations" subtab. -Hit the "Add Integration" button on the integrations listing page to get to the form below. +From the organization settings page, select the _Integrations_ subtab. +Hit the _Add Integration_ button on the integrations listing page to get to the form below. To set up a Bitbucket Data Center / Server integration with Private Packagist, start by selecting "Bitbucket Data Center / Server" as the platform, enter the URL of your on-premise Bitbucket Data Center / Server into the base URL field and select OAuth 1 as the OAuth version as seen in the example below. @@ -38,17 +38,17 @@ Submit the form to see the additional information. ![Packagist Form](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-oauth1-02-packagist-details-20250103.png) ## Configure Application link -Click on the link to setup an Application Link on Bitbucket Data Center / Server. You will need the "Client Id" and the "Public Key" shown in the form. +Click on the link to setup an Application Link on Bitbucket Data Center / Server. You will need the _Client Id_ and the _Public Key_ shown in the form. ![Bitbucket Data Center / Server Configure Application Link](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-03-bitbucket-configure-application-link.png) For Bitbucket Data Center versions 7.21 and newer, select "Atlassian product" and not "External application" to be able to set up an OAuth1 link. -After you hit the button to create a new Application Link a configuration window may appear. If it does, verify that the url matches the "Application URL for Link" (_https://packagist.com_) and hit "Continue", otherwise skip this step. +After you hit the button to create a new Application Link a configuration window may appear. If it does, verify that the url matches the _Application URL for Link_ (_https://packagist.com_) and hit _Continue_, otherwise skip this step. ![Bitbucket Data Center / Server Invalid Url](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-04-bitbucket-invalid-url.png) -Now setup a "Generic Application". The only field required is the "Application Name". Submit the form to finish creating the Application Link. +Now setup a _Generic Application_. The only field required is the _Application Name_. Submit the form to finish creating the Application Link. ![Bitbucket Data Center / Server Setup Link](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-05-bitbucket-setup-link.png) @@ -58,12 +58,12 @@ Click on the pen icon to the right of the application you just created to edit t ![Bitbucket Data Center / Server Incoming Auth](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-07-bitbucket-incoming-auth.png) -This is where we will need the "Client ID" and the "Public Key" that were previously generated on the Private Packagist integration form. -Enter the "Client ID" into the "Consumer Key" field, make sure the entire content of the "Public Key" field gets copied and the "Consumer Callback" field stays empty. +This is where we will need the _Client ID_ and the _Public Key_ that were previously generated on the Private Packagist integration form. +Enter the _Client ID_ into the _Consumer Key_ field, make sure the entire content of the _Public Key_ field gets copied and the _Consumer Callback_ field stays empty. Submit the form and go back to the list of integrations in Private Packagist. ### Share the Bitbucket login link -The final step is sharing your organization-specific login link with your users. Look for the "Login link" button next to +The final step is sharing your organization-specific login link with your users. Look for the _Login link_ button next to your newly created Bitbucket Data Center / Server integration on the integrations page, and copy the URL. ![Bitbucket Data Center / Server integrations](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-oauth1-08-integrations-overview.png) diff --git a/docs/dependabot-for-private-packagist.md b/docs/dependabot-for-private-packagist.md index a0f9ce9c..95f142b6 100644 --- a/docs/dependabot-for-private-packagist.md +++ b/docs/dependabot-for-private-packagist.md @@ -8,7 +8,7 @@ This guide explains how to configure and set up Dependabot if you want to use it ## Enable Dependabot in GitHub -Start in your GitHub repository and go to “Settings”. In the “Security” section of the sidebar go to “Code security and analysis”, where you can enable Dependabot. In this process, you will create a dependabot.yaml [as shown as below](#dependabotyaml). Follow [this guide on GitHub](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide#enabling-dependabot-for-your-repository) for the complete steps to enable Dependabot. +Start in your GitHub repository and go to _Settings_. In the _Security_ section of the sidebar go to _Code security and analysis_, where you can enable Dependabot. In this process, you will create a dependabot.yaml [as shown as below](#dependabotyaml). Follow [this guide on GitHub](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide#enabling-dependabot-for-your-repository) for the complete steps to enable Dependabot. ![enable dependabot](/Resources/public/img/docs/articles/dependabot-secret.png) @@ -37,19 +37,19 @@ registries: Replace the Composer URL `https://repo.packagist.com/acme/` with your organization's Composer URL on packagist.com. The example URL is for the organization named `acme`. -To grant Dependabot access to the packages on Private Packagist, you need to provide the secret `PRIVATE_PACKAGIST_AUTH_TOKEN` to your GitHub repository. In Settings, under the section “Security,” there is a “Secrets and Variables” page for Dependabot. +To grant Dependabot access to the packages on Private Packagist, you need to provide the secret `PRIVATE_PACKAGIST_AUTH_TOKEN` to your GitHub repository. In _Settings_, under the section _Security_, there is a _Secrets and Variables_ page for Dependabot. ![Dependabot Secrets](/Resources/public/img/docs/articles/dependabot-secret.png) -Now, on Private Packagist, create an authentication token with update access under “Settings” and “Authentication Tokens”. Copy the secret token into the GitHub form. +Now, on Private Packagist, create an authentication token with update access under _Settings_ and _Authentication Tokens_. Copy the secret token into the GitHub form. ## Troubleshooting -To check if Dependabot is able to access your packages, navigate to “Insights” on your GitHub repository, then “Dependency Graph” and then activate the tab “Dependabot”. +To check if Dependabot is able to access your packages, navigate to _Insights_ on your GitHub repository, then _Dependency Graph_ and then activate the tab _Dependabot_. ![Dependabot Insights](/Resources/public/img/docs/articles/dependabot-insights.png) -There is a link “Recent update jobs”, that will show the last jobs from Dependabot and logs. The last job should be green now. +There is a link _Recent update jobs_, that will show the last jobs from Dependabot and logs. The last job should be green now. ![Dependabot Jobs](/Resources/public/img/docs/articles/dependabot-jobs.png) diff --git a/docs/mirror-magento-marketplace.md b/docs/mirror-magento-marketplace.md index e0c257fd..a4a73898 100644 --- a/docs/mirror-magento-marketplace.md +++ b/docs/mirror-magento-marketplace.md @@ -5,22 +5,22 @@ Private Packagist supports mirroring Composer repositories which require authent Mirrored packages show up in your Private Packagist search results, your [License Review](../features/license-review.d), and can be installed from your Private Packagist repository with Composer. Their distribution files are cached in your Private Packagist organization to make downloads redundant and faster. -To setup credentials for a repository, “Magento Marketplace” in our example, head to Settings > Manage Credentials in your Private Packagist organization. Afterwards you can add a new mirrored third party repository under Settings as well. From then on packages can be manually or automatically mirrored based on your configuration. +To setup credentials for a repository, "Magento Marketplace" in our example, head to _Settings > Manage Credentials_ in your Private Packagist organization. Afterwards you can add a new mirrored third party repository under _Settings_ as well. From then on packages can be manually or automatically mirrored based on your configuration. ## Magento Marketplace Walkthrough -Start by hitting “Manage Credentials” in your organizations settings. My organization is called “ACME Company”. +Start by hitting _Manage Credentials_ in your organizations settings. My organization is called "ACME Company". ![Manage Credentials](/Resources/public/img/docs/features/magento/Magento-Credentials-20200723.png) -Next enter a description, I’m going with “Magento Marketplace Credentials”, and select “Magento Marketplace” as the authentication type. The domain “repo.magento.com” will be filled in automatically. Now we need the Magento Marketplace Public and Private Key, we’ll click on “My Access Keys” to get to the Magento Marketplace website. +Next enter a description, I'm going with "Magento Marketplace Credentials", and select "Magento Marketplace" as the authentication type. The domain "repo.magento.com" will be filled in automatically. Now we need the Magento Marketplace Public and Private Key, we'll click on _My Access Keys_ to get to the Magento Marketplace website. ![Create Credentials](/Resources/public/img/docs/features/magento/Magento-Credentials-Edit-20200723.png) -Make sure you’re on the Magento 2 Access Keys page, and then copy and paste the Private and Public keys into the respective fields on Private Packagist. Once you’re done, hit “Create” on the Private Packagist Credentials page. +Make sure you're on the Magento 2 Access Keys page, and then copy and paste the Private and Public keys into the respective fields on Private Packagist. Once you're done, hit _Create_ on the Private Packagist Credentials page. ![Magento Access Keys](/Resources/public/img/docs/features/magento/Magento-Access-Keys.png) -With the credentials set up we can now mirror a new Composer repository under Settings in the Private Packagist organization. +With the credentials set up we can now mirror a new Composer repository under _Settings_ in the Private Packagist organization. ![Mirror Settings](/Resources/public/img/docs/features/magento/Magento-Settings-Mirror-20200723.png) @@ -28,11 +28,11 @@ Pick a name for the repository, I picked “Magento Marketplace”, enter the UR ![Mirror Add](/Resources/public/img/docs/features/magento/Magento-Mirror-Add-20200723.png) -Under Packages we can now add a package “From Mirror”. +Under Packages we can now add a package _From Mirror_. ![Packages Add](/Resources/public/img/docs/features/magento/Magento-Packages-Add-2020723.png) -I’m going to enter just one package for the demo, but you can add as many as you like here. I’m going with “magento/module-catalog”. Make sure to select the “Magento Marketplace” Mirror repository underneath, and hit “Add”. +I'm going to enter just one package for the demo, but you can add as many as you like here. I'm going with "magento/module-catalog". Make sure to select the "Magento Marketplace" Mirror repository underneath, and hit _Add_. ![Packages Add Proxied](/Resources/public/img/docs/features/magento/Magento-Add-Mirrored-20200723.png) diff --git a/docs/notifications.md b/docs/notifications.md index f9bcaab6..1c9bde72 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -35,7 +35,7 @@ Notification channels allow you to receive notifications via other means than em - **Microsoft Teams Webhook**: Sends notifications to your configured Microsoft Teams channel - **Webhook**: Sends an HTTP POST request to a defined URL optionally signed with a user supplied secret. -Notification channels can be added on your organization’s settings page under *Notification Channels -> Add Notification Channel*. +Notification channels can be added on your organization’s settings page under _Notification Channels -> Add Notification Channel_. ### Receiving Webhook Notifications diff --git a/docs/security-monitoring.md b/docs/security-monitoring.md index d20c7356..bed465c8 100644 --- a/docs/security-monitoring.md +++ b/docs/security-monitoring.md @@ -25,7 +25,7 @@ Organizations using subroganizations have the option to disable security monitor Every user receives security notifications by email for all projects they have access to by default. Users can unsubscribe either from individual projects or from all security notifications if they do not wish to receive any email notifications. -[Notification channels](./notifications.md) allow you to receive security notifications via email to other addresses, on Slack, on Microsoft Teams or through a webhook to an endpoint of your choice. They can be configured on your organization’s settings page under *Notification Channels -> Add Notification Channel*. +[Notification channels](./notifications.md) allow you to receive security notifications via email to other addresses, on Slack, on Microsoft Teams or through a webhook to an endpoint of your choice. They can be configured on your organization’s settings page under _Notification Channels -> Add Notification Channel_. Once you create a notification channel, you can assign it to the packages to be monitored on the organization's security settings. diff --git a/docs/self-hosted/authentication-email-addresses-passwords-setup.md b/docs/self-hosted/authentication-email-addresses-passwords-setup.md index a2036c40..84d849f8 100644 --- a/docs/self-hosted/authentication-email-addresses-passwords-setup.md +++ b/docs/self-hosted/authentication-email-addresses-passwords-setup.md @@ -4,7 +4,7 @@ ## Setup By default, authentication with email addresses and passwords is disabled. If possible, we recommend setting up authentication with your installation of [GitHub (Enterprise)](./github-integration-setup.md), [Bitbucket.org](./bitbucket-integration-setup.md), [Bitbucket Data Center / Server](./bitbucket-server-integration-setup.md), or [GitLab](./gitlab-integration-setup.md) using OAuth instead. -Navigate to the "Global Configuration" section from the admin page to get to the form below. -Enable login and account registration with email addresses and passwords by selecting the option in the form and submitting the form via the "Update configuration" button. +Navigate to the _Global Configuration_ section from the admin page to get to the form below. +Enable login and account registration with email addresses and passwords by selecting the option in the form and submitting the form via the _Update configuration_ button. ![Packagist Setup](/Resources/public/img/docs/integration-setup/self-hosted/login-password-01-packagist-setup-20250103.png) diff --git a/docs/self-hosted/bitbucket-server-oauth1-integration-setup.md b/docs/self-hosted/bitbucket-server-oauth1-integration-setup.md index 0506a9cb..43355988 100644 --- a/docs/self-hosted/bitbucket-server-oauth1-integration-setup.md +++ b/docs/self-hosted/bitbucket-server-oauth1-integration-setup.md @@ -26,7 +26,7 @@ To allow your users to authenticate to Private Packagist with their Bitbucket Da first need to create an integration in Private Packagist. This document walks you through the required steps. ## Open the Add Integration form -Go to the Admin section and hit the “Add Integration“ button to open the form to create your integration. If you've just +Go to the Admin section and hit the _Add Integration_ button to open the form to create your integration. If you've just installed Private Packagist Self-Hosted and it is still running in Setup Mode, you do not need to log in. If the application is no longer in Setup mode, you will have to log in with an admin account first. @@ -42,17 +42,17 @@ Submit the form to see the additional information. ![Packagist Form](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-server-oauth1-02-packagist-form.png) ## Configure Application link -Click on the link to setup an Application Link on Bitbucket Data Center / Server. You will need the "Client Id" and the "Public Key" shown in the form. +Click on the link to setup an Application Link on Bitbucket Data Center / Server. You will need the _Client Id_ and the _Public Key_ shown in the form. ![Bitbucket Data Center / Server Configure Application Link](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-03-bitbucket-configure-application-link.png) For Bitbucket Data Center versions 7.21 and newer, select "Atlassian product" and not "External application" to be able to set up an OAuth1 link. -After you hit the button to create a new Application Link a configuration window may appear. If it does, verify that the url matches your Private Packagist URL and hit "Continue", otherwise skip this step. +After you hit the button to create a new Application Link a configuration window may appear. If it does, verify that the url matches your Private Packagist URL and hit _Continue_, otherwise skip this step. ![Bitbucket Data Center / Server Invalid Url](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-04-bitbucket-invalid-url.png) -Now setup a "Generic Application". The only field required is the "Application Name". Submit the form to finish creating the Application Link. +Now setup a _Generic Application_. The only field required is the _Application Name_. Submit the form to finish creating the Application Link. ![Bitbucket Data Center / Server Setup Link](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-05-bitbucket-setup-link.png) @@ -62,8 +62,8 @@ Click on the pen icon to the right of the application you just created to edit t ![Bitbucket Data Center / Server Incoming Auth](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-07-bitbucket-incoming-auth.png) -This is where we will need the "Client ID" and the "Public Key" that were previously generated on the Private Packagist integration form. -Enter the "Client ID" into the "Consumer Key" field, make sure the entire content of the "Public Key" field gets copied and the "Consumer Callback" field stays empty. +This is where we will need the _Client ID_ and the _Public Key_ that were previously generated on the Private Packagist integration form. +Enter the _Client ID_ into the _Consumer Key_ field, make sure the entire content of the _Public Key_ field gets copied and the _Consumer Callback_ field stays empty. Submit the form and go back to Private Packagist. ## Finish the Setup diff --git a/docs/self-hosted/installation.md b/docs/self-hosted/installation.md index dd2057ce..01c9efe6 100644 --- a/docs/self-hosted/installation.md +++ b/docs/self-hosted/installation.md @@ -70,7 +70,7 @@ Select options for your SMTP server or use the GMail option for a simplified for ![Email Settings](/Resources/public/img/docs/self-hosted/05-email-settings.png) ## Application Startup -Save and apply the settings to start Private Packagist Self-Hosted. Leave the Setup Mode enabled. +Save and apply the settings to start Private Packagist Self-Hosted. Leave the _Setup Mode_ enabled. ![Start Application](/Resources/public/img/docs/self-hosted/06-save-start.png) @@ -80,13 +80,13 @@ Once the application has started, click on the open link to access the Private P ## Configuring an HTTP Proxy If accessing websites outside of your network, e.g. packagist.org, requires an HTTP proxy then you can -enable and configure this in the Console Settings under the HTTP Proxy section which you can access in +enable and configure this in the _Console Settings_ under the _HTTP Proxy_ section which you can access in the Replicated management console by clicking on the gear icon in the menu bar. ![HTTP Proxy](/Resources/public/img/docs/self-hosted/07-01-http-proxy.png) In case the HTTP proxy should not be used to access certain domains or IPs then you can configure such -a NO_PROXY list in the Private Packagist application in the Admin Panel under Global Configuration. +a NO_PROXY list in the Private Packagist application in the _Admin Panel_ under _Global Configuration_. ![No HTTP Proxy](/Resources/public/img/docs/self-hosted/07-02-http-proxy-no-proxy.png) @@ -110,7 +110,7 @@ The first user is granted admin permissions automatically. You can grant admin p ![Add Admin](/Resources/public/img/docs/self-hosted/10-add-admin.png) ## Switching to Production Mode -Head back to the Replicated management console to disable the Setup Mode in Settings. +Head back to the Replicated management console to disable the _Setup Mode_ in _Settings_. ![Startup Mode](/Resources/public/img/docs/self-hosted/11-startup-mode.png) @@ -121,7 +121,7 @@ Apply the changes and wait while the application restarts. That’s it! Private Packagist Self-Hosted is now ready to be used! You’ll find all further information in the web interface. ## Backups -Once the application is running you can create a snapshot in the management console using the “Start Snapshot” button. You can view a list of all snapshots created under “Snapshots” when you click on the gear icon on the menu bar. Further you can configure automatic regular snapshots in the “Console Settings” after clicking on the gear icon. We recommend you configure Snapshots to store files via SFTP or on S3 instead of locally to avoid a very slow snapshot process. +Once the application is running you can create a snapshot in the management console using the _Start Snapshot_ button. You can view a list of all snapshots created under _Snapshots_ when you click on the gear icon on the menu bar. Further you can configure automatic regular snapshots in the _Console Settings_ after clicking on the gear icon. We recommend you configure Snapshots to store files via SFTP or on S3 instead of locally to avoid a very slow snapshot process. Snapshot are stored in ``/var/lib/replicated/snapshots`` on the Replicated host. This location may not be suitable for keeping large amounts of data. Additionally, by default, it is likely to be on the same physical volume as all other critical data. We highly recommend this location is configured to be on a separate volume with large capacity to ensure data can be recovered in case of a disaster. diff --git a/docs/self-hosted/kubernetes-troubleshooting.md b/docs/self-hosted/kubernetes-troubleshooting.md index 414383e6..69b1190e 100644 --- a/docs/self-hosted/kubernetes-troubleshooting.md +++ b/docs/self-hosted/kubernetes-troubleshooting.md @@ -20,8 +20,8 @@ kubectl delete pods --field-selector status.phase=Failed -n kurl #### Generating a support bundle You can generate a support bundle from the Replicated management console on port -8800 by navigating to the Troubleshoot tab, clicking "Generate a support bundle", -and selecting "Analyze". +8800 by navigating to the _Troubleshoot_ tab, clicking _Generate a support bundle_, +and selecting _Analyze_. Once the analysis is done, either download the bundle and manually send it to us or click on the send icon which will send us the bundle. Please always notify us if you send us a support bundle! diff --git a/docs/self-hosted/troubleshooting.md b/docs/self-hosted/troubleshooting.md index c3d7a9e3..e2a84203 100644 --- a/docs/self-hosted/troubleshooting.md +++ b/docs/self-hosted/troubleshooting.md @@ -24,8 +24,8 @@ the logs in this file yourself as well. #### Generating a support bundle You can generate a support bundle from the Replicated Management Console on -port 8800 by navigating to the Support tab and clicking on the "Download -Support Bundle" button. Alternatively you can use replicated's command line +port 8800 by navigating to the _Support_ tab and clicking on the _Download +Support Bundle_ button. Alternatively you can use replicated's command line interface to generate the support bundle on your host system: `replicatedctl support-bundle` @@ -124,8 +124,8 @@ update the host IP and the NO_PROXY environment. You just updated to Self-Hosted version 1.12.4 and now the Replicated Management Console only shows "Stopped" in the top left corner of the dashboard? As part of this this Self-Hosted update PostgreSQL is upgraded from 9.6 to 12. Depending on the size of your database, this will cause increased disk IO and might take a few minutes during which the application won't be available. -The upgrade is done in the docker container `packagist-postgres-update` which only runs for the duration of the upgrade and then stops. You can check the `Cluster` section in the Replicated Management Console: all containers should be started except the upgrade container, which should be stopped. The Replicated Management Console is just showing the wrong state on the dashboard. -Pressing the button `Start now` on the dashboard will correct the displayed application state, but you can also leave it as is. +The upgrade is done in the docker container `packagist-postgres-update` which only runs for the duration of the upgrade and then stops. You can check the _Cluster_ section in the Replicated Management Console: all containers should be started except the upgrade container, which should be stopped. The Replicated Management Console is just showing the wrong state on the dashboard. +Pressing the _Start now_ button on the dashboard will correct the displayed application state, but you can also leave it as is. #### Reset Replicated Management Console authentication diff --git a/docs/setup-ci-cd.md b/docs/setup-ci-cd.md index 79c880cb..7c78eb9d 100644 --- a/docs/setup-ci-cd.md +++ b/docs/setup-ci-cd.md @@ -4,7 +4,7 @@ You can use read-only tokens to grant automated systems like continuous integrat ## Adding a read-only token to your organization -You can add read-only tokens on your organization's settings page under *Authentication Tokens*. Make sure to select "Read-only access to packages" on the access dropdown. +You can add read-only tokens on your organization's settings page under _Authentication Tokens_. Make sure to select _Read-only access to packages_ on the access dropdown. Once the token is created, you'll need to add `COMPOSER_AUTH` as an environment variable in your CI/CD. ``` @@ -20,7 +20,7 @@ Listed below are some examples for using Private Packagist with different CI/CD ### GitHub Actions -For GitHub actions, you can add the `COMPOSER_AUTH` environment variable at the repository level by going to the repository settings -> secrets -> new repository secret. Environment variables can then be used in your [workflow files](https://docs.github.com/en/actions/learn-github-actions/environment-variables#about-environment-variables). +For GitHub actions, you can add the `COMPOSER_AUTH` environment variable at the repository level by going to _repository settings > secrets > new repository secret_. Environment variables can then be used in your [workflow files](https://docs.github.com/en/actions/learn-github-actions/environment-variables#about-environment-variables). If you are using [shivammathur/setup-php](https://github.com/shivammathur/setup-php) watch out that it overwrites `COMPOSER_AUTH` if you configure a `COMPOSER_TOKEN`. Instead of using `COMPOSER_TOKEN` you can define the entire environment variable yourself including GitHub's token: diff --git a/docs/setup-suborganization.md b/docs/setup-suborganization.md index 65a25c63..72fc80cd 100644 --- a/docs/setup-suborganization.md +++ b/docs/setup-suborganization.md @@ -29,7 +29,7 @@ one for Drupal 7 and one for Drupal 8. Then change your composer.json in all Com ## Setting up a suborganization in Private Packagist -Organization owners and admins can create suborganizations on the suborganizations page via the "Create suborganization" button. +Organization owners and admins can create suborganizations on the suborganizations page via the _Create suborganization_ button. On the settings page of an individual team you can grant all members of a team permission to create suborganizations. Alternatively, you can create suborganizations using our API through the [API client](https://github.com/packagist/private-packagist-api-client) with the following code snippet: @@ -83,8 +83,8 @@ $client->suborganizations()->mirroredRepositories()->add($suborganizationName, [ ### Adding packages -Existing packages can be shared into the suborganization via "Add Package" -> "Organization Packages". -Select all necessary packages and add them to the suborganization, you can select to add their dependencies too. If you need to create new packages in a suborganization you can add them using the "Add Package" dialog and the previously set up credentials. +Existing packages can be shared into the suborganization via _Add Package > Organization Packages_. +Select all necessary packages and add them to the suborganization, you can select to add their dependencies too. If you need to create new packages in a suborganization you can add them using the _Add Package_ dialog and the previously set up credentials. Mirrored packages will automatically be added to your suborganization on use via composer commands. We do not recommend manually adding them to your suborganization. @@ -142,7 +142,7 @@ Working on a Composer project with external developers might sometimes require t to make sure they can run composer install and update and help manage the project's dependencies. Adding them as suborganization collaborators will only grant them access to selected suborganizations and not give them access to you your Private Packagist organization. -You can invite via email suborganization collaborators on the suborganization's team page via the "Manage Collaborators" button. +You can invite via email suborganization collaborators on the suborganization's team page via the _Manage Collaborators_ button. ## Setting up CI / CD environments diff --git a/docs/setup.md b/docs/setup.md index e5c79dbf..f2dc1292 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -132,13 +132,13 @@ Without Private Packagist, every time you run `composer update` Composer loops t It then checks whether the branch/tag contains a valid composer.json. Especially for repositories with lots of tags or branches this can take a long time. -You can add repositories to Private Packagist on the Packages page by clicking on *Add Package -> By Url*, selecting the type *VCS* and entering its URL. For private repositories requiring authentication you need to select a credential as explained in the next section. +You can add repositories to Private Packagist on the Packages page by clicking on _Add Package > By Url_, selecting the type _VCS_ and entering its URL. For private repositories requiring authentication you need to select a credential as explained in the next section. If you add a repository hosted on GitHub, GitLab, Bitbucket or Bitbucket Server using a credential, then Private Packagist will automatically set up a webhook to get notified about new commits and versions. Therefore it is beneficial to use a credential even if the repository is publicly available. Repositories where no webhook can be set up will only be updated once every 12 hours. ### Private VCS repository requiring authentication -For Private Packagist to be able to access repositories that require authentication, e.g. a private GitHub repository, we first need to set up a credential under *Settings -> Stored Credentials*. Once the credential is created the repository can be added on the Packages page via *Add Package -> By Url*. +For Private Packagist to be able to access repositories that require authentication, e.g. a private GitHub repository, we first need to set up a credential under _Settings > Stored Credentials_. Once the credential is created the repository can be added on the Packages page via *Add Package > By Url*. Note: Even though you need to select a domain when you create a credential Private Packagist will not automatically apply the credential for all HTTP calls to that domain. Private Packagist will only suggest it where it might be useful. Therefore it is important that you explicitly select it when you add the credential or else Private Packagist will not be able to import the repository. @@ -169,7 +169,7 @@ When adding a fork to Private Packagist it can happen that the original package ## Add a custom package -Custom package definitions in your composer.json can be added via *Add Package -> Custom Package*. In the textarea you are then able to paste the entire package definition and select a credential if one is necessary to access the zip files. +Custom package definitions in your composer.json can be added via _Add Package > Custom Package_. In the textarea you are then able to paste the entire package definition and select a credential if one is necessary to access the zip files. Example: ```json @@ -230,11 +230,11 @@ This placeholder package will prevent any other package with the same name from ## Add an artifact package -You can upload code archives via *Add Package -> Artifact*. Your uploaded archives need to contain a valid composer.json file in its root directory and must be of type zip, gz, or bz2. Once you upload your code archives, you can save the artifact package and use it in your organization. +You can upload code archives via _Add Package > Artifact_. Your uploaded archives need to contain a valid composer.json file in its root directory and must be of type zip, gz, or bz2. Once you upload your code archives, you can save the artifact package and use it in your organization. ## Import from an existing Satis instance -Once you start using Private Packagist it usually also replaces your previous Satis setup. Via *Add Package -> Json Import* you can paste your satis.json into the textarea and select which credentials should be used to try to import the packages. This will add all packages from your Satis instance to Private Packagist and will make Satis obsolete and therefore one less thing you have to worry about. +Once you start using Private Packagist it usually also replaces your previous Satis setup. Via _Add Package > Json Import_ you can paste your satis.json into the textarea and select which credentials should be used to try to import the packages. This will add all packages from your Satis instance to Private Packagist and will make Satis obsolete and therefore one less thing you have to worry about. ## Add mirrored third party repositories On your organization’s settings page under “Manage Mirrored Repositories” you can add additional third party mirrored repositories. By default packagist.org is enabled for all organizations so there is no need to set that up. @@ -243,7 +243,7 @@ Similar to how Private Packagist can access private VCS repositories it can also If you are moving one of the additional Composer repositories to Private Packagist after you already started to use Private Packagist, make sure to run `composer update mirrors` again to update the download locations for packages from the mirror in your lock file. -*Important Note:* Third party repositories do not provide a way for us to get notified whenever new versions of a package appear. Therefore packages which have been added via mirror will only be updated once every 12 hours. +**Important:** Third party repositories do not provide a way for us to get notified whenever new versions of a package appear. Therefore packages which have been added via mirror will only be updated once every 12 hours. ## Cleanup Once all the repository entries have been added to Private Packagist the setup is complete and you can remove all the repositories so it will look exactly like what you see in the snippet on your Organization’s overview page.