This is primarily aimed at deploying from Visual Studio to an Azure Web App + Azure SQL database, feel free to skip bits that aren’t relevant if you’re doing other things.
Prerequisites for developing locally:
Visual Studio (obviously)
Ensure IIS URL Rewrite module is installed using web platform installer (other downloads from MS documentation don’t seem to work)
Set up Azure:
Make a new SQL Database in Azure, take note of the server name, database name, admin login and admin password. If you already have a server and resource group, automate with Powershell as shown below (you’ll need to replace the param values):New-AzureRmSqlDatabase -DatabaseName “UmbracoDatabase” -ServerName “TheServer” -ResourceGroupName “Whatever” -Edition “Basic"
Add your IP to the Azure SQL db firewall so Umbraco can connect to it later when running locally
Create a new Azure web app, either manually or via Powershell:New-AzureRmWebApp -ResourceGroupName “Whatever” -Name “UmbracoWebsite” -Location “AustraliaEast” -AppServicePlan “YourASP"
Set “PHP Version” to “Off"
Create the project:
Open VS and make a new ASP.NET Web Application, targeting the latest release version of .NET, and select the “Empty” project template
Open the Package Manager Console, and run “Install-Package UmbracoCms"
Once that’s done, build & run your VS solution (debug mode is fine)
Put your admin account details into the install page
Click “Customize”, not “Install”!
Select “Microsoft SQL Azure” as the target database and enter the server/admin details
Probably don’t install a starter pack
If everything worked, you should be logged into the Umbraco backend on localhost
Pre-deployment:
Set <customErrors mode="Off” /> in web.config. Remember to change this back later.
Delete the Umbraco/Install folder
Copy the .gitignore from https://github.com/github/gitignore/blob/master/Umbraco.gitignore to your project’s root and obviously save as .gitignore
While you’re at it, make sure you have a Visual Studo gitignore set up too: https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
Do the usual new git project stuff: git init / add / commit / remote add origin / push origin master
Include \App_Data\ in the solution, but only \App_Data\packages, and \App_Data\Models\ (and the models once you’ve compiled your models, depending on your ModelsBuilder setting). Exclude everything else under \App_Data\ like logs, nugetbackup, temp and umbraco.config etc.
If you were using a starter kit, include everything from that too (make sure you have “Show all files” selected in Solution Explorer)
Add this URL rewrite rule to redirect from /admin to /umbraco:
<rewrite>
<rules>
<rule name="Umbraco Admin” enabled="true” stopProcessing="true”>
<match url="^admin$” />
<action type="Redirect” url=”/umbraco” appendQueryString="false” redirectType="Temporary” />
</rule>
</rules>
</rewrite>
While you’re at it, make sure you have a Visual Studo gitignore set up too: https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
Do the usual new git project stuff: git init / add / commit / remote add origin / push origin master
Include \App_Data\ in the solution, but only \App_Data\packages, and \App_Data\Models\ (and the models once you’ve compiled your models, depending on your ModelsBuilder setting). Exclude everything else under \App_Data\ like logs, nugetbackup, temp and umbraco.config etc.
If you were using a starter kit, include everything from that too (make sure you have “Show all files” selected in Solution Explorer)
Add this URL rewrite rule to redirect from /admin to /umbraco:
<rewrite>
<rules>
<rule name="Umbraco Admin” enabled="true” stopProcessing="true”>
<match url="^admin$” />
<action type="Redirect” url=”/umbraco” appendQueryString="false” redirectType="Temporary” />
</rule>
</rules>
</rewrite>
Deployment:
Publish via VS’ web publish (right click project node, “Publish”)
Don’t use git-based deployments because the contents of \Media\ changes whenever users upload files, and a git-based deployment will erase any changes they make there.
It’s easier to use Azure blob storage for media (see below) to avoid storing media files inside the site at all. But if you’re leaving media in \Media, make sure you keep the git repo up-to-date. Before a publish always right-click “Media” in VS and select “Replace Media from server”. Publishing without doing this won’t delete people’s file uploads, but any file links will break if you ever try to clone the site from git.
Azure AD integration
https://www.jdibble.co.uk/blog/securing-umbraco-backoffice-with-azure-active-directory/
https://stackoverflow.com/questions/40301349/azure-ad-identity-doesnt-seem-to-provide-email-for-auto-linking-umbraco-user
Azure blob storage integration:
Using the “media” folder to store media sucks if you’re using source control and are running a large site with lots of constantly-changing media files. There’s a better way! Install this package: https://www.nuget.org/packages/UmbracoFileSystemProviders.Azure/
And then configure it like this: https://github.com/JimBobSquarePants/UmbracoFileSystemProviders.Azure
Don’t use git-based deployments because the contents of \Media\ changes whenever users upload files, and a git-based deployment will erase any changes they make there.
It’s easier to use Azure blob storage for media (see below) to avoid storing media files inside the site at all. But if you’re leaving media in \Media, make sure you keep the git repo up-to-date. Before a publish always right-click “Media” in VS and select “Replace Media from server”. Publishing without doing this won’t delete people’s file uploads, but any file links will break if you ever try to clone the site from git.
Azure AD integration
https://www.jdibble.co.uk/blog/securing-umbraco-backoffice-with-azure-active-directory/
https://stackoverflow.com/questions/40301349/azure-ad-identity-doesnt-seem-to-provide-email-for-auto-linking-umbraco-user
Azure blob storage integration:
Using the “media” folder to store media sucks if you’re using source control and are running a large site with lots of constantly-changing media files. There’s a better way! Install this package: https://www.nuget.org/packages/UmbracoFileSystemProviders.Azure/
And then configure it like this: https://github.com/JimBobSquarePants/UmbracoFileSystemProviders.Azure
Setting up Umbraco itself:
Setting up your document types can happen either locally or on the server (since they write to the same db)
Always do all your coding (like templates) locally in Visual Studio, commit to git and deploy to the server. Don’t edit code within Umbraco itself, unless you aren’t using version control and don’t care about Visual Studio’s vastly superior editor, debugging, etc.
If you don’t know what to do from here, go to http://umbraco.tv/ and learn how to Umbraco ;)
If you don’t know what to do from here, go to http://umbraco.tv/ and learn how to Umbraco ;)
Remember to put <customErrors mode="Off” /> back to how it was in web.config (either “RemoteOnly” or ideally “On” with some error handling)
Set up google analytics (optional)
Set up app insights (optional). Note that it’ll add some stuff to the <log4net> section of web.config, which broke it during automated setup. Copy the new content into config\log4net.config
Go through everything in Umbraco’s back office -> Developer -> Health Check
Once everything is set up and you’re ready to launch the site:
The below isn’t essential, but useful:
Turn Umbraco’s logging off (/config/umbracoSettings.config)
Set umbracoDebugMode to false
Set up custom error pages
Set custumerrors mode="Off"
Set <compilation debug="false” />
Set <trace enabled="false"
Set umbracoDisableVersionCheck to true
Add the following in the disabledLogTypes node:
<logTypeAlias>debug</logTypeAlias>
<logTypeAlias>notfound</logTypeAlias>
<logTypeAlias>open</logTypeAlias>
<logTypeAlias>packagerinstall</logTypeAlias>
<logTypeAlias>packageruninstall</logTypeAlias>
<logTypeAlias>ping</logTypeAlias>
Remote debugging:
This feature is so handy I thought I’d make a section for it
In Visual Studio, do a web deploy in “Debug” mode
In the Server Explorer pane, find your web app, right click and select “Attach Debugger"
Obviously make sure to set “Remote debugging” to “Off” in the Azure Web App “Application Settings” page once you’re done. It turns off automatically in 48 hours anyway, but still.
Obviously make sure to set “Remote debugging” to “Off” in the Azure Web App “Application Settings” page once you’re done. It turns off automatically in 48 hours anyway, but still.
Other points:
This is an excellent checklist of other things:
https://github.com/engern/Umbraco-Deployment-Checklist
The easiest way to make a copy of the SQL database for testing is to click the “Copy” button on the database’s “Overview” page in Azure. These are priced at cents per hour, so just delete it when you’re done testing. It’s so easy to make a new one that you probably don’t need to keep it around once you’re done.
Otherwise if you want to load it elsewhere, click “Export” and save a backup, then download that and restore to another database of your choice.
Sync file updates from Azure to VS (e.g. when people upload files)
Azure AD integration:
First do this:
https://www.jdibble.co.uk/blog/securing-umbraco-backoffice-with-azure-active-directory/
Then do this:
https://stackoverflow.com/questions/40301349/azure-ad-identity-doesnt-seem-to-provide-email-for-auto-linking-umbraco-user
In web.config, change the “owin:appStartup” key’s value to “UmbracoStandardOwinStartup"
Remember to add the app’s URL including /umbraco to the list of reply URL’s in Azure
Inside the code block for new OpenIdConnectAuthenticationOptions:
Change the “email” line of AuthorizationCodeReceived to:
var email = context.JwtSecurityToken.Claims.First(x => x.Type == “upn”).Value;
Change the “if user == null” part to
if (user == null)
{
user = userService.CreateUserWithIdentity(email, email);//, writerUserType);
}
Change the last bit to:
adOptions.SetExternalSignInAutoLinkOptions(new ExternalSignInAutoLinkOptions(autoLinkExternalAccount: true, defaultUserGroups: new string[] { “writer” }, defaultCulture: null));
TODO: ModelsBuilder modes
Other sources not already mentioned:
https://our.umbraco.org/documentation/getting-started/setup/install/install-umbraco-with-nuget
https://caveofcode.com/2016/03/how-to-setup-umbraco-locally-and-on-azure/