Skip to content

Add docker documentation for V14 and V15 #6588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Oct 30, 2024
Merged

Add docker documentation for V14 and V15 #6588

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
00473eb
Add docker documentation
nikolajlauridsen Oct 23, 2024
65c54dc
fixes
nikolajlauridsen Oct 23, 2024
d28fd7f
Apply suggestions from code review
nikolajlauridsen Oct 28, 2024
05a1027
Add suggestion from review
nikolajlauridsen Oct 28, 2024
6c0c24d
Copy changes to V15
nikolajlauridsen Oct 28, 2024
3cb7841
Update SUMMARY.md
sofietoft Oct 30, 2024
737dfcc
Update SUMMARY.md
sofietoft Oct 30, 2024
2389127
Update release-candidate-guide.md
sofietoft Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 90 additions & 46 deletions 14/umbraco-cms/fundamentals/setup/install/install-umbraco-with-templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,54 +37,98 @@ From that command's output, you will get a better understanding of what are the
Umbraco Project (C#)
Author: Umbraco HQ
Description: An empty Umbraco project ready to get started.
Options:
-v|--version The version of Umbraco.Cms to add as PackageReference.
string - Optional
Default: 10.0.0

--use-https-redirect Adds code to Program.cs to redirect HTTP to HTTPS and enables the UseHttps setting.
bool - Optional
Default: false

--no-restore If specified, skips the automatic restore of the project on create.
bool - Optional
Default: false

--exclude-gitignore Whether to exclude .gitignore from the generated template.
bool - Optional
Default: false

--minimal-gitignore Whether to only include minimal (Umbraco specific) rules in the .gitignore.
bool - Optional
Default: false

--connection-string Database connection string used by Umbraco.
string - Optional

--connection-string-provider-name Database connection string provider name used by Umbraco.
string - Optional
Default: Microsoft.Data.SqlClient
Usage:
dotnet new umbraco [options] [template options]

--development-database-type Database type used by Umbraco for development.
None - Do not configure a database for development.
SQLite - Use embedded SQLite database.
LocalDB - Use embedded LocalDB database (requires SQL Server Express with Advanced Services).
Default: None

--friendly-name Used to specify the name of the default admin user when using unattended install on development (stored as plain text).
string - Optional

--email Used to specify the email of the default admin user when using unattended install on development (stored as plain text).
string - Optional

--password Used to specify the password of the default admin user when using unattended install on development (stored as plain text).
string - Optional

--no-nodes-view-path Path to a custom view presented with the Umbraco installation contains no published content.
string - Optional

-p|--PackageTestSiteName The name of the package project this should be a test site for.
string - Optional
Options:
-n, --name <name> The name for the output being created. If no name is specified, the name of the output directory is used.
-o, --output <output> Location to place the generated output.
--dry-run Displays a summary of what would happen if the given command line were run if it would result in a template
creation.
--force Forces content to be generated even if it would change existing files.
--no-update-check Disables checking for the template package updates when instantiating a template.
--project <project> The project that should be used for context evaluation.
-lang, --language <C#> Specifies the template language to instantiate.
--type <project> Specifies the template type to instantiate.

Template options:
-r, --release <Latest|LTS> The Umbraco release to use, either latest or latest long term supported
Type: choice
Latest The latest umbraco release
LTS The most recent long term supported version
Default: Latest
--use-https-redirect Adds code to Startup.cs to redirect HTTP to HTTPS and enables the UseHttps setting.
Type: bool
Default: false
-da, --use-delivery-api Enables the Delivery API
Type: bool
Default: false
--add-docker Adds a docker file to the project.
Type: bool
Default: false
--no-restore If specified, skips the automatic restore of the project on create.
Type: bool
Default: false
--exclude-gitignore Whether to exclude .gitignore from the generated template.
Type: bool
Default: false
--minimal-gitignore Whether to only include minimal (Umbraco specific) rules in the .gitignore.
Type: bool
Default: false
--connection-string <connection-string> Database connection string used by Umbraco.
Type: string
--connection-string-provider-name Database connection string provider name used by Umbraco.
<connection-string-provider-name> Type: string
Default: Microsoft.Data.SqlClient
--development-database-type <choice> Database type used by Umbraco for development.
Type: choice
None Do not configure a database for development.
SQLite Use embedded SQLite database.
LocalDB Use embedded LocalDB database (requires SQL Server Express with Advanced
Services).
Default: None
--friendly-name <friendly-name> Used to specify the name of the default admin user when using unattended install on
development (stored as plain text).
Type: string
--email <email> Used to specify the email of the default admin user when using unattended install on
development (stored as plain text).
Type: string
--password <password> Used to specify the password of the default admin user when using unattended install on
development (stored as plain text).
Type: string
--no-nodes-view-path <no-nodes-view-path> Path to a custom view presented with the Umbraco installation contains no published
content.
Type: string
-dm, --development-mode <choice> Choose the development mode to use for the project.
Type: choice
BackofficeDevelopment Enables backoffice development, allowing you to develop from
within the backoffice, this is the default behaviour.
IDEDevelopment Configures appsettings.Development.json to Development runtime
mode and SourceCodeAuto models builder mode, and configures appsettings.json to
Production runtime mode, Nothing models builder mode, and enables UseHttps
Default: BackofficeDevelopment
-mm, --models-mode <choice> Choose the models builder mode to use for the project. When development mode is set to
IDEDevelopment this only changes the models builder mode appsetttings.development.json
Type: choice
Default Let DevelopmentMode determine the models builder mode.
InMemoryAuto Generate models in memory, automatically updating when a content
type change, this means no need for app rebuild, however models are only available in
views.
SourceCodeManual Generate models as source code, only updating when requested
manually, this means a interaction and rebuild is required when content type(s) change,
however models are available in code.
SourceCodeAuto Generate models as source code, automatically updating when a
content type change, this means a rebuild is required when content type(s) change,
however models are available in code.
Nothing No models are generated, this is recommended for production assuming
generated models are used for development.
Default: Default
-sk, --starter-kit <choice> Choose a starter kit to install.
Type: choice
None No starter kit.
Umbraco.TheStarterKit The Umbraco starter kit.
Default: None
```

## Create an Umbraco project
Expand Down
97 changes: 97 additions & 0 deletions 14/umbraco-cms/fundamentals/setup/install/running-umbraco-on-docker-locally.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
description: "Running Umbraco on docker locally using docker compose"
---

# Running Umbraco in Docker using Docker Compose

To aid in developing Umbraco with additional services, the templates can provide the requisite files to run Umbraco with a SQL Server database in Docker.
This setup is designed to be used for local development, and not for production.

## Prerequisites

Before you can run Umbraco in Docker, you need to have the following installed:
* Version 14.3.0 or higher of the Umbraco Templates
* Docker Desktop

## Installing

Installing Umbraco with the Docker file and Docker Compose file is a two-step process.

First, create a folder to hold your project and enter that folder.

```bash
mkdir MyDockerProject
cd MyDockerProject
```
Next create your Umbraco project using the Umbraco Templates, and remember to use the `--add-docker` flag to include the Docker files.
Conventionally this is named the same as the folder, but is not a requirement.

```bash
dotnet new umbraco -n MyDockerProject --add-docker
```

Now we need to add some additional files to make docker compose work. We can do this using the `umbraco-compose` template, passing the project name we specified earlier to the `-P` parameter:

```bash
dotnet new umbraco-compose -P "MyDockerProject"
```

The `-P` flag is required to specify the correct paths in the docker-compose file. The project is now ready to run with docker compose.

The final folder structure looks like this:

* MyDockerProject
* MyDockerProject
* Typical project files
* DockerFile
* .dockerignore
* .env
* Database
* DockerFile
* healthcheck.sh

Check warning on line 51 in 14/umbraco-cms/fundamentals/setup/install/running-umbraco-on-docker-locally.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.ListStart] Start each option with a capital letter.

Raw Output:
{"message": "[UmbracoDocs.ListStart] Start each option with a capital letter.", "location": {"path": "14/umbraco-cms/fundamentals/setup/install/running-umbraco-on-docker-locally.md", "range": {"start": {"line": 51, "column": 7}}}, "severity": "WARNING"}
* setup.sql

Check warning on line 52 in 14/umbraco-cms/fundamentals/setup/install/running-umbraco-on-docker-locally.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.ListStart] Start each option with a capital letter.

Raw Output:
{"message": "[UmbracoDocs.ListStart] Start each option with a capital letter.", "location": {"path": "14/umbraco-cms/fundamentals/setup/install/running-umbraco-on-docker-locally.md", "range": {"start": {"line": 52, "column": 7}}}, "severity": "WARNING"}
* startup.sh
* docker-compose.yml

As you can see the project now includes docker files for both Umbraco itself and the SQL server database, as well as some additional scripts to launch and configure the database.

It also includes a .env file with the password for the database.

## Running

To run the project run the `docker compose up` command from the root of the project, same folder as `docker-compose.yml`.

This command will build both the Umbraco and Sql Server images and launch them in the correct order, after a while the site will have booted and you can navigate to it in your browser like nomral on `http://localhost:44372/`

### Useful commands

There is some useful commands you can use to manage the docker containers:

* `docker compose down --volumes` This will delete your containers and the volumes they use, this is useful if you want to start from scratch.

{% hint style="warning" %}
This delete your database and all data in it, so be careful with this command.
{% endhint %}

* `docker compose up --build` This will rebuild the images and start the containers, this is useful if you have made changes to the project and want to see them reflected in the running site.
* `docker compose watch` This will start the containers and watch the default models folder, this means that if the project uses source code models builder the images automatically rebuilds and restarts when you change the models.

## Details

The docker compose file uses bind mounts for the following folders:

* /wwwroot/media
* /wwwroot/scripts
* /wwwroot/css
* /Views
* /models

This is bad for production, however, for local development this means that the files necessary for development are available from outside the container in your IDE allowing you to effectively develop even though the project is running in docker.

## Template options

The `umbraco-compose` template has a few options that can be used to customize the setup:

* -P or --project-name: The name of the project, this is required and used to set the correct paths in the docker-compose file.
* -dbpw or --DatabasePasswor: Used to specify the database password, this is stored in the .env file, defaults to: Password1234
* -p or --Port: Used to specify the port the site will run on, defaults to 44372
Loading
Loading