diff --git a/website/docs/containers/registries/_insecure-registry-linux.md b/website/docs/containers/registries/_insecure-registry-linux.md
deleted file mode 100644
index fc05cb303799..000000000000
--- a/website/docs/containers/registries/_insecure-registry-linux.md
+++ /dev/null
@@ -1,37 +0,0 @@
-#### Prerequisites
-
-- Podman is installed.
-
-#### Procedure
-
-1. Add your insecure registry within ** Settings > Registries**.
-
- 
-
-1. Click "Yes" to the insecure registry warning.
-
- 
-
-1. Open `registries.conf`.
-
- ```shell-session
- $ sudo vi /etc/containers/registries.conf
- ```
-
-1. Add the insecure registry: Add a new `[[registry]]` section for the URL of the insecure registry you want to use. For example, if your insecure registry is located at `http://registry.example.com`, add the following lines:
-
- ```toml
- [[registry]]
- location = "registry.example.com"
- insecure = true
- ```
-
- If you have multiple registries, you can add one `[[registry]]` block per registry:
-
-1. Save and exit the file.
-
-1. Restart Podman.
-
- ```shell-session
- $ sudo systemctl restart podman
- ```
diff --git a/website/docs/containers/registries/_insecure-registry-windows-macos.md b/website/docs/containers/registries/_insecure-registry-windows-macos.md
deleted file mode 100644
index 9c2a364bd98b..000000000000
--- a/website/docs/containers/registries/_insecure-registry-windows-macos.md
+++ /dev/null
@@ -1,44 +0,0 @@
-#### Prerequisites
-
-- [A running Podman machine](/docs/podman/installing).
-
-#### Procedure
-
-1. Add your insecure registry within ** Settings > Registries**.
-
- 
-
-1. Click "Yes" to the insecure registry warning.
-
- 
-
-1. SSH into the Podman Machine to edit `registries.conf`.
-
- ```shell-session
- $ podman machine ssh [optional-machine-name]
- ```
-
-1. Open `registries.conf`.
-
- ```shell-session
- $ sudo vi /etc/containers/registries.conf
- ```
-
-1. Add the insecure registry: Add a new `[[registry]]` section for the URL of the insecure registry you want to use. For example, if your insecure registry is located at `http://registry.example.com`, add the following lines:
-
- ```toml
- [[registry]]
- location = "registry.example.com"
- insecure = true
- ```
-
- If you have multiple registries, you can add one `[[registry]]` block per registry.
-
-1. Save and exit the file.
-
-1. Restart Podman by the CLI or through Podman Desktop.
-
- ```shell-session
- $ podman machine stop
- $ podman machine start
- ```
diff --git a/website/docs/containers/registries/_verification-private-registry.md b/website/docs/containers/registries/_verification-private-registry.md
deleted file mode 100644
index 07373b8d1506..000000000000
--- a/website/docs/containers/registries/_verification-private-registry.md
+++ /dev/null
@@ -1,8 +0,0 @@
-#### Verification
-
-1. Go to ** Images**.
-1. You can pull a private image from the registry.
-1. You can push an image to the registry:
- 1. Build an image with the fully qualified name required for your registry, such as `quay.io/my-repository/my-image`, `ghcr.io/my-repository/my-image`, `docker.io/my-repository/my-image`, or `my-registry.tld/my-repository/my-image`.
- 1. On your image line, click ****.
- 1. The contextual menu has a **Push Image** entry.
diff --git a/website/docs/containers/registries/authenticating-to-a-preconfigured-registry.md b/website/docs/containers/registries/authenticating-to-a-preconfigured-registry.md
deleted file mode 100644
index e649581b872d..000000000000
--- a/website/docs/containers/registries/authenticating-to-a-preconfigured-registry.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-sidebar_position: 10
-title: Authenticating to a registry
-description: Authenticating to a pre-configured registry.
-keywords: [podman desktop, podman, containers, registry, registries]
-tags: [images]
----
-
-import Verification from './\_verification-private-registry.md'
-
-# Authenticating to a pre-configured registry
-
-With Podman Desktop, you can authenticate to a set of pre-configured registries:
-
-- Red Hat Quay
-- Docker Hub
-- GitHub
-- Google Container registry
-
-#### Prerequisites
-
-- You have credentials on a pre-configured image registry.
-
-#### Procedure
-
-1. Go to ** Settings > Registries**.
-1. On your registry line, click **Configure**.
-
- 1. **User name**: Enter your user name.
- 1. **Password**: Enter your password or OAuth secret.
- 1. Click **Login**.
-
- 
-
-
diff --git a/website/docs/containers/registries/index.md b/website/docs/containers/registries/index.md
index 455bbcfb4fa0..e9f905159e8f 100644
--- a/website/docs/containers/registries/index.md
+++ b/website/docs/containers/registries/index.md
@@ -2,18 +2,252 @@
sidebar_position: 3
title: Registries
description: Working with container registries
-tags: [podman-desktop, containers, registries]
+tags: [podman-desktop, containers]
keywords: [podman desktop, podman, containers, registries]
hide_table_of_contents: false
+image: /img/docs/containers/registries/img/registries.png
---
-# Working with container registries
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
-Podman Desktop has access to public registries by default.
+# Setting up container registries
-You might want to configure Podman Desktop to:
+:::tip[Before you start]
-- [Authenticate to a preconfigured registry](/docs/containers/registries/authenticating-to-a-preconfigured-registry).
-- [Add an Insecure Registry to Podman Desktop](/docs/containers/registries/insecure-registry).
+Before you start, you should:
-
+- Get authentication details for your container registry:
+ - Registry URL.
+ - User name.
+ - Password, or OAuth secret.
+- Get the fully qualified name of a private image stored in your registry, such as `my-registry.tld/my-repository/my-image`.
+- Get the fully qualified image name that your registry requires to push an image, such as `my-registry.tld/my-repository/my-image`.
+
+:::
+
+## Setting up a pre-configured registry
+
+To ease usage of the most popular container registries, Podman Desktop has pre-configured registries, including:
+
+- Docker Hub
+- Red Hat Quay
+- GitHub
+- Google Container Registry
+
+If your container registry is in this list, follow the steps:
+
+1. Go to ** Settings > Registries**.
+2. In your registry line, click **Configure**.
+3. Enter your registry credentials:
+
+ 
+
+ 1. **Username**: Enter your user name.
+ 2. **Password**: Enter your password or OAuth secret.
+ 3. Click **Login**.
+
+Podman Desktop logs Podman in with the provided credentials.
+
+If you enter the wrong credentials, you see an error message:
+
+1. Enter the correct credentials
+2. Click **Login** again.
+
+## Setting up a custom registry
+
+You have a custom container registry, or one that is not available in the pre-configured list: we have got you covered. Follow the steps:
+
+1. Go to ** Settings > Registries**.
+1. Click ** Add registry** at the top right corner of the screen.
+1. Enter your registry details:
+
+ 
+
+ 1. **Registry Location**: Enter your repository URL, such as `https://myregistry.tld`.
+ 2. **Username**: Enter your user name.
+ 3. **Password**: Enter your password or OAuth secret.
+ 4. Click **Login**.
+
+Podman Desktop logs Podman in with the provided credentials.
+
+If you enter the wrong credentials, you see an error message:
+
+1. Enter the correct credentials
+2. Click **Login** again.
+
+## Setting up a registry with an insecure certificate
+
+If your registry has an insecure certificate, such as a self-signed certificate, you see a warning when setting up the registry.
+
+1. In the **Invalid Certificate** window, click **Yes** to add the registry anyway.
+
+ 
+
+1. Tell Podman that it has your authorization to access the insecure registry: edit the `registries.conf` file.
+
+ 1. Go to a location where you can edit the `registries.conf` file:
+
+
+
+
+ - The configuration file is in the Podman machine: open a terminal in the Podman Machine.
+
+ ```shell-session
+ $ podman machine ssh [optional-machine-name]
+ ```
+
+
+
+
+ - The configuration file is in the Podman machine: open a terminal in the Podman Machine.
+
+ ```shell-session
+ $ podman machine ssh [optional-machine-name]
+ ```
+
+
+
+
+ - The configuration file is in your host: open a terminal with superuser privileges.
+
+ ```shell-session
+ $ sudo su -
+ ```
+
+
+
+
+ 1. Edit the registry optional configuration file.
+
+ ```shell-session
+ # vim /etc/containers/registries.conf`
+ ```
+
+ For each insecure registry, add a `[[registry]]` section that defines:
+
+ - `location =`: Enter your registry URL.
+ - `insecure = true`: Accept the insecure certificate.
+
+ For example, if your have two registries, such as `https://my-registry.tld` and `http://registry.example.com`, add the following lines:
+
+ ```toml
+ [[registry]]
+ location = "my-registry.tld"
+ insecure = true
+
+ [[registry]]
+ location = "registry.example.com"
+ insecure = true
+ ```
+
+1. Restart Podman to apply the changes.
+
+
+
+
+ 1. Go to ** Settings > Resources**.
+ 1. Restart the Podman machine.
+
+
+
+
+ 1. Go to ** Settings > Resources**.
+ 1. Restart the Podman machine.
+
+
+
+
+ - Stop all Podman processes.
+
+ ```shell-session
+ $ pkill podman
+ ```
+
+
+
+
+ - Restart Podman.
+
+ ```shell-session
+ $ sudo systemctl restart podman
+ ```
+
+
+
+
+## Verifying your registry setup
+
+To verify your registry has been properly configured, you can do the following steps:
+
+1. In ** Settings > Registries**, the line with your registry has content in the Username and Password column, and action icons replacing the Configure button.
+
+1. Pull a private image from the registry.
+
+ 1. Get the name of a private image stored in your registry, such as `quay.io/my-repository/my-image`, `ghcr.io/my-repository/my-image`, `docker.io/my-repository/my-image`, or `my-registry.tld/my-repository/my-image`.
+ 1. Go to **Images**.
+ 1. Click **Pull an image**.
+ 1. On the **Image to Pull** screen:
+ 1. **Image to pull**: Enter the image name.
+ 1. Click Pull image.
+ 1. Click Done.
+
+1. Push an image to the registry:
+
+ 1. Get the fully qualified image name that your registry requires, such as `quay.io/my-repository/my-image`, `ghcr.io/my-repository/my-image`, or `docker.io/my-repository/my-image`.
+ 1. Go to **Images**.
+ 1. Click **Build an image**.
+ 1. On the **Build Image from Containerfile** screen
+ 1. **Containerfile path**: select the Containerfile or Dockerfile to build.
+ 2. **Image Name**: enter the fully qualified image name that your registry requires.
+ 3. Click Build.
+ 4. Click Done.
+ 1. On your image line, click ****.
+
+ The contextual menu has a **Push Image to _your registry_** entry.
+
+## Changing your credentials
+
+To change your registry credentials, you can do the following steps:
+
+1. Go to ** Settings > Registries**.
+1. On your registry line, click ****.
+1. Click **Edit password**.
+1. Enter your credentials in the **Username** and **Password** fields, and click **Login**.
+
+Podman Desktop logs Podman in with the updated credentials.
+
+## Removing a registry
+
+To remove your registry, you can do the following steps:
+
+1. Go to ** Settings > Registries**.
+1. On your registry line, click ****.
+1. Click Remove.
+
+Podman Desktop removes the registry from the settings, and logs Podman out from the registry.
+
+## Finding Podman registry configuration files
+
+Podman has two files to configure registries:
+
+- `auth.json` defines the authentication to registries.
+
+ Podman Desktop stores this file directly on your host, in `$HOME/.config/containers/auth.json`.
+
+ The Podman machine mounts the authentication configuration file to access it.
+
+ When you delete the Podman machine, the registry configuration is not lost: it stays on your host.
+
+- `registries.conf` defines optional features, such as allowing insecure certificates.
+
+ The Podman machine stores the file in `/etc/containers/registries.conf`.
+
+ When you delete the Podman machine, this file is deleted.
+
+## Next steps
+
+Consider completing some other common tasks that depend registries:
+
+- Pulling an image.
+- Pushing an image to a registry.
diff --git a/website/docs/containers/registries/insecure-registry.md b/website/docs/containers/registries/insecure-registry.md
deleted file mode 100644
index 9723c5a4e8b7..000000000000
--- a/website/docs/containers/registries/insecure-registry.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-sidebar_position: 10
-title: Adding an insecure registry
-description: Modifying Podman for an insecure registry
-keywords: [podman desktop, podman, containers, registry, podman machine]
-tags: [pods]
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import WindowsMacosProcedure from './\_insecure-registry-windows-macos.md'
-import LinuxProcedure from './\_insecure-registry-linux.md'
-import Verification from './\_verification-private-registry.md'
-
-# Adding an Insecure Registry to Podman Desktop
-
-In this guide, you will learn how to add an insecure registry to Podman Desktop. An insecure registry allows you to pull and push container images either over an unencrypted HTTP connection, or a HTTPS connection with a self-signed unverified certificate. Please note that using an insecure registry can expose your data to security risks, so it's recommended to use secure connections with a verifiable certificate whenever possible.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 615704cf6102..f23d22c4f3b8 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -262,17 +262,14 @@ const config = {
from: ['/docs/working-with-containers', '/docs/getting-started/getting-started', '/docs/getting-started'],
},
{
- to: '/docs/containers/registries/authenticating-to-a-preconfigured-registry',
+ to: '/docs/containers/registries',
from: [
- '/docs/working-with-containers/registries/authenticating-to-a-preconfigured-registry',
+ '/docs/containers/registries/authenticating-to-a-preconfigured-registry',
+ '/docs/containers/registries/insecure-registry',
'/docs/getting-started/authenticating-to-a-preconfigured-registry',
- ],
- },
- {
- to: '/docs/containers/registries/insecure-registry',
- from: [
- '/docs/working-with-containers/registries/insecure-registry',
'/docs/getting-started/insecure-registry',
+ '/docs/working-with-containers/registries/authenticating-to-a-preconfigured-registry',
+ '/docs/working-with-containers/registries/insecure-registry',
],
},
{