diff --git a/content/manuals/_index.md b/content/manuals/_index.md index 630d92371d0..e195000e6a1 100644 --- a/content/manuals/_index.md +++ b/content/manuals/_index.md @@ -59,6 +59,10 @@ params: description: Run integration tests, with real dependencies, in the cloud. icon: package_2 link: https://testcontainers.com/cloud/docs/ + - title: Docker Projects + description: Use a unified, project-based workflow to run your containerized projects. + icon: folder + link: /projects/ platform: - title: Administration description: Centralized observability for companies and organizations. diff --git a/content/manuals/projects/_index.md b/content/manuals/projects/_index.md new file mode 100644 index 00000000000..f22baa89169 --- /dev/null +++ b/content/manuals/projects/_index.md @@ -0,0 +1,52 @@ +--- +title: Docker Projects +params: + sidebar: + group: Products + badge: + color: blue + text: Beta +weight: 50 +description: Learn how to use Docker Projects which provides a unified, project-based workflow to run your containerized projects. +keywords: Docker, projects, docker deskotp, containerization +grid: +- title: How Docker Projects works + description: Learn How Docker Projects works + icon: category + link: /projects/about/ +- title: Open a new project + description: Learn how to open a new local or remote projects. + icon: checklist + link: /projects/open/ +- title: Edit your project + description: Edit your project's run commands and setup. N + icon: design_services + link: /projects/edit/ +- title: Manage your projects + description: Run or remove your projects. + icon: tune + link: /projects/manage/ +- title: View your projects + description: View detailed information about your projects and services within your projects + icon: visibility + link: /projects/view/ +- title: FAQs + description: View common FAQs about Docker Projects + icon: help + link: /projects/faq/ +--- + +{{< summary-bar feature_name="Docker Projects" >}} + +Docker Projects provides a simplified, project-based workflow for running and managing containerized applications. It organizes your code, configurations, and logs across local and cloud environments into a single view, making it easy to collaborate and share across teams. + +A project organizes your code and Docker artifacts into a single object. These artifacts include logs as well as customizable run commands. These artifacts can persist remotely in the cloud, which lets you access your projects from any device that has Docker Desktop. + +### Key features and benefits + + - One-click project setup: Open a local folder or clone a Git repository and run your project instantly. + - Minimal Docker expertise required: Ideal for both beginners and experienced developers. + - Custom `run` commands for your projects: Define and store pre-configured `run` commands that are equivalent to running `docker compose up`. + - Local and remote projects: Work on projects locally or sync artifacts to the cloud for cross-device access and easy collaboration. + +{{< grid >}} diff --git a/content/manuals/projects/about.md b/content/manuals/projects/about.md new file mode 100644 index 00000000000..d7f81fa1a6c --- /dev/null +++ b/content/manuals/projects/about.md @@ -0,0 +1,45 @@ +--- +title: How it works +description: Understand how Docker Projects works +keywords: docker projects +weight: 10 +--- + +Docker Projects requires a Compose file (`compose.yml`) to define your application's services, networks, and configurations. When you open a project, Docker Projects automatically detects the Compose file, allowing you to configure and run services with pre-set commands. + +By integrating with Docker Compose, Docker Projects ensures a consistent, easy-to-manage workflow for both individual developers and teams. Whether you're starting a new project, configuring it, or collaborating with a team, Docker Projects keeps the process simple. + +Docker Projects works as follows: + +1. Create or open a project. You can: + + - Open a local project: Select a folder on your machine that contains your project code. + - Clone a Git repository: Provide a repository URL and clone the project into a local directory. + + Once a project is opened, Docker Desktop detects the Compose file and prepares the project for execution. + +2. Configure and run your project with pre-configured commands. These commands: + + - Work like `docker compose up`, launching services based on the Compose file. + - Can be customized with additional flags, multiple Compose files, and environment variables. + - Enable pre-run tasks, such as executing scripts before starting the services. + + All of which means you can fine-tune your configurations without manually running complex CLI commands. + +3. Collaborate and share with teams. For projects linked to a Git repository, Docker Projects stores artifacts in the cloud, enabling easy collaboration: + + - Work across devices: Open a project from any machine and instantly access stored configurations. + - Share configurations: Team members can access pre-defined run commands, reducing setup time. + + Collaboration is easy — new developers can join a team, open a project, and start working without complex setup steps. + +4. Manage and iterate. Once a project is up and running, Docker Projects makes it easy to monitor, update, and troubleshoot: + + - View logs to debug issues and track service activity. + - Edit configurations and run commands as requirements change. + +## What's next + + - [Learn how to open a new project](/manuals/projects/open.md) + - [Explore common FAQs](/manuals/projects/faq.md) + diff --git a/content/manuals/projects/edit.md b/content/manuals/projects/edit.md new file mode 100644 index 00000000000..0021fe98f7a --- /dev/null +++ b/content/manuals/projects/edit.md @@ -0,0 +1,47 @@ +--- +title: Add or edit your run commands +description: Learn how to add or edit your run commands in Docker Projects +keywords: Docker, projects, docker deskotp, containerization, open, remote, local, run commands +weight: 40 +--- + +## Add a run command to a project + +1. Open an existing project and ensure that it is stopped. + +2. From the command drop-down menu, select **New run command**. + +3. Specify the following information for the run command: + + > [!TIP] + > + > While configuring your run command, you can view the equivalent `docker compose up` command in the **Run command** section on the configuration page. You can also use this command to run your project from the command line. You can refer to the [`docker compose up` reference documentation](/reference/cli/docker/compose/up.md) to learn more about the options you configure. + + - **Name**: Specify a name to identify the run command. + - **Compose files**: Select one or more Compose files from your project. + - **Flags**: Optionally, select one or more flags for your run command. + + > [!TIP] + > + > While the `--env-file` flag isn't currently supported, you can specify environment variables in your Compose file, or use the **Tasks** option to run a script that sets your environment variables. + + - **Services that will run**: After selecting one or more Compose files, the services defined in the files will appear here. If there is more than one service, you can optionally choose to not run a service by deselecting the checkbox. + - **Tasks (Advanced options)**: Optionally specify a command to run before running the project. For example, if you want to run a bash script from the project directory named `set-vars.sh`, you can specify bash `set-vars.sh`. Or, on Windows, to run a script with `cmd.exe` named `set-vars.bat`, specify `set-vars.bat`. Note that a task can access environment variables from your terminal profile, but it can't access local shell functions nor aliases. + +4. Select **Save changes**. + +You can now select the new run command from the drop-down menu after opening the project. + +## Edit a run command + +1. Open an existing project and ensure that it is stopped. + +2. Select the run command you want to change from the command drop-down menu. + +3. Select the **Edit** icon next to the **Run** button. + +4. Specify your changes and then select **Save changes**. + +## What's next? + + - [Manage your projects](/manuals/projects/manage.md) \ No newline at end of file diff --git a/content/manuals/projects/faq.md b/content/manuals/projects/faq.md new file mode 100644 index 00000000000..88628a55506 --- /dev/null +++ b/content/manuals/projects/faq.md @@ -0,0 +1,22 @@ +--- +title: Docker Projects FAQs +linkTitle: FAQs +description: Find common FAQs for Docker Projects +keywords: faqs, docker projects, local, remote +weight: 70 +--- + +## Why is a Compose file required? + +A Compose file (`compose.yml`) defines how your application's containers should run together, including: + + - Services (e.g., web, database, API) + - Networks for inter-container communication + - Volumes for persistent data storage + - Environment variables and configurations + +Without a Compose file, Docker Projects doesn't have a way to understand how your application should be structured or executed. + +## What if my project doesn’t have a Compose file? + +If your project doesn't include a `compose.yml` file, you need to create one before opening it in Docker Projects. \ No newline at end of file diff --git a/content/manuals/projects/manage.md b/content/manuals/projects/manage.md new file mode 100644 index 00000000000..097b609d819 --- /dev/null +++ b/content/manuals/projects/manage.md @@ -0,0 +1,37 @@ +--- +title: Manage your projects +description: Learn how to delete or completely remove a project. +keywords: Docker, projects, docker deskotp, containerization, open, remote, local +weight: 50 +--- + +## Run a project or service + +1. Open a new or existing project. + +2. Select a run command from the drop-down menu. + +3. Select the **Run** button for the project or the **Play** button next to the service you'd like to run. + +## Stop or restart a project or service + +1. Open an existing project that is running. + +2. Select the **Stop** or **Restart** button for the project or the appropriate button next to the service. + +## Remove a project from Docker Desktop + +If a project is associated with a Git repository, you can remove it from Docker Desktop. When a project is deleted, you can no longer run the project from the **Projects** view, but its run configuration still exists remotely in the cloud. + +This means that you can later [open the project](/manuals/projects/open.md#open-an-existing-remote-project) and associate it with the remote run configuration without having to specify the run command again. +None of your local code is deleted when removing a project from Docker Desktop. + +To remove a project from Docker Desktop: + +1. Sign in to Docker Desktop, and go to **Projects**. + +2. Select the **More actions** menu next to the project, and then select **Remove from Docker Desktop**. + +## Delete a project + +Deleting a project removes it from Docker Desktop and deletes all configuration locally and remotely from the cloud. When a project is deleted, you can no longer run the project from the **Projects** view. None of your local code is deleted when you delete a project from Docker Desktop. diff --git a/content/manuals/projects/open.md b/content/manuals/projects/open.md new file mode 100644 index 00000000000..001c06c3c91 --- /dev/null +++ b/content/manuals/projects/open.md @@ -0,0 +1,121 @@ +--- +title: Open a new project +description: Learn how to open a new local or remote project, or an existing project in Docker Projects. +keywords: Docker, projects, docker deskotp, containerization, open, remote, local +weight: 20 +--- + +> [!IMPORTANT] +> +> To use Docker Projects, you must enable the **Access experimental features** setting in Docker Desktop. See [Features in development](/manuals/desktop/settings-and-maintenance/settings.md#features-in-development) for more information. + +## New projects + +To run a new project, it must be stored locally. In the **Projects** view in Docker Desktop, local projects display the local path under the project. + +### Open a new local project + +A project consists of your code and at least one Compose file. Ensure that you have a Compose file before trying to open a new project. + +To open a new project: + +1. Sign in to Docker Desktop, and go to **Projects**. + +2. Select **Open a local folder**. This lets you select a local folder that contains your project’s code and a Compose file. + + > [!NOTE] + > + > A local folder can also be the folder of a Git repository that you have already cloned. + +3. Configure your project by giving it a name and setting the owner, then select **Next**. + + > [!NOTE] + > + > If you are part of a Docker organization you have the option to [share your project](share.md) with the organization. + +4. Specify how to run your project by selecting **New run command**: + + > [!TIP] + > + > While configuring your run command, you can view the equivalent `docker compose up` command in the **Run command** section on the configuration page. You can also use this command to run your project from the command line. You can refer to the [`docker compose up` reference documentation](/reference/cli/docker/compose/up.md) to learn more about the options you configure. + + - **Name**: Specify a name to identify the run command. + - **Compose files**: Select one or more Compose files from your project. + - **Flags**: Optionally, select one or more flags for your run command. + + > [!TIP] + > + > While the `--env-file` flag isn't currently supported, you can specify environment variables in your Compose file, or use the **Tasks** option to run a script that sets your environment variables. + + - **Services that will run**: After selecting one or more Compose files, the services defined in the files will appear here. If there is more than one service, you can optionally choose to not run a service by deselecting the checkbox. + - **Tasks (Advanced options)**: Optionally specify a command to run before running the project. For example, if you want to run a bash script from the project directory named `set-vars.sh`, you can specify bash `set-vars.sh`. Or, on Windows, to run a script with `cmd.exe` named `set-vars.bat`, specify `set-vars.bat`. Note that a task can access environment variables from your terminal profile, but it can't access local shell functions nor aliases. + +5. Select **Save changes**. + +Your project is now ready to run. + +### Open a new remote project + +The following steps prompt you to clone the Git repository for your project. + +If you have already cloned the repository outside of Docker Projects, then you can open the project as a new project and Docker Projects will automatically detect and link the repository. + +To clone and open a remote project: + +1. Sign in to Docker Desktop, and go to **Projects**. + +2. Select **Clone a git repository**. This lets you specify a Git repository and a local folder to clone that repository to. The repository must contain at least your project’s code and a Compose file. + +3. Enter the remote source and choose the local destination to clone to. + +4. Select **Clone project**. + +5. Configure your project by giving it a name and setting the owner, then select **Next**. + + > [!NOTE] + > + > If you are part of a Docker organization you have the option to [share your project](share.md) with the organization. + +6. Specify how to run your project by selecting **New run command**: + + > [!TIP] + > + > While configuring your run command, you can view the equivalent `docker compose up` command in the **Run command** section on the configuration page. You can also use this command to run your project from the command line. You can refer to the [`docker compose up` reference documentation](/reference/cli/docker/compose/up.md) to learn more about the options you configure. + + - **Name**: Specify a name to identify the run command. + - **Compose files**: Select one or more Compose files from your project. + - **Flags**: Optionally, select one or more flags for your run command. + + > [!TIP] + > + > While the `--env-file` flag isn't currently supported, you can specify environment variables in your Compose file, or use the **Tasks** option to run a script that sets your environment variables. + + - **Services that will run**: After selecting one or more Compose files, the services defined in the files will appear here. If there is more than one service, you can optionally choose to not run a service by deselecting the checkbox. + - **Tasks (Advanced options)**: Optionally specify a command to run before running the project. For example, if you want to run a bash script from the project directory named `set-vars.sh`, you can specify bash `set-vars.sh`. Or, on Windows, to run a script with `cmd.exe` named `set-vars.bat`, specify `set-vars.bat`. Note that a task can access environment variables from your terminal profile, but it can't access local shell functions nor aliases. + +7. Select **Save changes**. + +## Existing projects + +### Open an existing local project + +1. Sign in to Docker Desktop, and go to **Projects**. + +2. Open your project by selecting your project under **Recents**, or by selecting the specific owner that your project is associated with and then select your project. + +### Open an existing remote project + +In the **Projects** view in Docker Desktop, existing remote projects display **No local copy** under the project. + +You’ll see remote projects when you are new to the team and are accessing a shared project, remove a project from Docker Desktop, or access Docker Desktop from a new device after creating a project associated with a Git repository. + +To open an existing remote project, you can choose between: + + - Cloning the project into a local destination. + - Linking to an existing folder where the project has already been cloned + +## What's next? + + - [View your project](/manuals/projects/view.md) + - [Add or edit your run commands](/manuals/projects/edit.md) + - [Manage your projects](/manuals/projects/manage.md) diff --git a/content/manuals/projects/share.md b/content/manuals/projects/share.md new file mode 100644 index 00000000000..70d7ee73ea9 --- /dev/null +++ b/content/manuals/projects/share.md @@ -0,0 +1,27 @@ +--- +title: Share and collaborate on a project +linkTitle: Collaborate +description: Learn how to collaborate on a project +keywords: collaborate, projects, docker desktop, local, remote +weight: 60 +--- + +Docker Projects makes it easy for teams to share, manage, and collaborate on containerized applications. + +Collaboration is managed by associating a project with a Docker organization, and leveraging cloud-stored configurations. This allows team members to easily access and work on the same project without needing extensive manual setup. + +Once a project is associated with an organization, other team members can access it by: + +1. Signing into Docker Desktop and navigating to **Projects**. + +2. Selecting the correct organization tab. + +3. Selecting the project from the list of shared projects. + +4. Cloning the project into a local destination. + +## What's next + + - [View your project](/manuals/projects/view.md) + - [Add or edit your run commands](/manuals/projects/edit.md) + - [Manage your projects](/manuals/projects/manage.md) diff --git a/content/manuals/projects/view.md b/content/manuals/projects/view.md new file mode 100644 index 00000000000..3e45b5490b4 --- /dev/null +++ b/content/manuals/projects/view.md @@ -0,0 +1,80 @@ +--- +title: View your project +description: View information about your project or the services within your project. +keywords: containers, docker projects, local, remote, docker desktop +weight: 30 +--- + +## View a project’s README + +If a project has a README file, you can view it via Docker Projects. Note that the README tab is only visible if the project has a README file. + +To view a project’s README, open a new or existing project and then select the README tab. + +## View logs for a project + +1. Open a new or existing project. + +2. Select the **Logs** tab to see all project logs. + +3. Optionally, use the menu in the top right corner of the logs to copy the logs to your clipboard or clear the logs. + +## View service-level information + +With Docker Projects, you can view the following information about your containers within your project: + + - Logs + - Image + - Files + - Network + - Environment variables + +From the **Exec** tab, you can use the integrated terminal, on a running container, directly within Docker Desktop. You are able to quickly run commands within your container so you can understand its current state or debug when something goes wrong. + +### Logs + +Select **Logs** to see logs from the containers in your project. You can also: + +- Use `Cmd + f`/`Ctrl + f` to open the search bar and find specific entries. + Search matches are highlighted in yellow. +- Press `Enter` or `Shift + Enter` to jump to the next or previous search match + respectively. +- Use the **Copy** icon in the top right-hand corner to copy all the logs to + your clipboard. +- Automatically copy any logs content by highlighting a few lines or a section + of the logs. +- Use the **Clear terminal** icon in the top right-hand corner to clear the + logs terminal. +- Select and view external links that may be in your logs. + +### Image + +The **Image** tab in Docker Projects provides details about the Docker image associated with a service. It helps you verify which image is being used, when it was last built, and where the corresponding Dockerfile is located. + +It also provides quick access to inspect the image or open the Dockerfile for modifications. + +### Files + +Select **Files** to explore the filesystem of running or stopped containers in your project. You +can also: + + - See which files have been recently added, modified, or deleted + - Edit a file straight from the built-in editor + - Drag and drop files and folders between the host and the container + - Delete unnecessary files when you right-click on a file + - Download files and folders from the container straight to the host + +### Network + +The **Network** tab in Docker Projects provides an overview of how the containerized services communicate with each other and the host system. It displays the assigned network name, connected services, and mapped container ports. + +If a service is mapped to a host port, you can select the link to open it in a browser + +### Environment variables + +The **Env** tab in Docker Projects displays the environment variables available to a service. These variables help configure the runtime environment without modifying the container image. + +## What's next? + + - [Add or edit your run commands](/manuals/projects/edit.md) + - [Manage your projects](/manuals/projects/manage.md) diff --git a/data/summary.yaml b/data/summary.yaml index 26802062250..88fbb30e289 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -134,6 +134,8 @@ Docker Desktop CLI update: requires: Docker Desktop 4.38 and later Docker GitHub Copilot: availability: Early Access +Docker Projects: + availability: Beta Docker Init: requires: Docker Desktop [4.27](/manuals/desktop/release-notes.md#4270) and later Docker Scout exceptions: