joey40 / github-move

Let's Encrypt Site Extension

This Azure Web App Site Extension enables easy installation and configuration of Let's Encrypt issued SSL certificates for you custom domain names.

The site extension requires that you have configured a DNS entry for your custom domain to point to Azure Web App.

November 2019 - Microsoft finally acknowledge that maybe it is in due time that they add first level support for free SSL certificates, see this announcement about App Service Managed Certificates, be aware that it is in preview and currently doesn't support the apex/naked domain.

How to install

https://github.com/sjkp/letsencrypt-siteextension/wiki/How-to-install

Known Issues

• This site-extension is NOT supported by Microsoft it is my own work based on https://github.com/fszlin/certes - this means don't expect 24x7 support, I use it for several of my own smaller sites, but if you are running sites that are important you should consider spending the few $ on a certificate and go with a Microsoft supported way of enabling SSL, so you have someone to blame :)
• Note that Let's Encrypt works by providing automated certificates of a short (currently three month) duration. This extension is BETA SOFTWARE. You will need to keep this extension updated or risk losing SSL access when your certificate expires.
• There are presently no email notifications for certificate renewal problems, but Lets Encrypt will email you weeks in advance of certificate expiration, when the extension is running properly the certificate should have been renewed before Let's Encrypt send the reminder email.
• Due to rate limiting of Let's Encrypt servers, you can only request five certificates per domain name per week. Configuration errors or errors in this site extension may render you unable to retrieve a new certificate for seven days. If up-time is critical, have a plan for deploying a SSL certificate from another source in place.
• No support for multi-region web apps, so if you use traffic manager or some other load balancer to route traffic between web apps in different regions please dont use this extension.
• If you publish your project from Visual Studio with the "Delete Existing files" option, you will remove the web jobs the site extension uses to renew the certificate once they expire every 3 months (you can renew them manually or install the site extension again after publish).
• The site-extension can now work with Azure App Service Local Cache, however you must do a little manual work, see https://github.com/sjkp/letsencrypt-siteextension/wiki/Azure-Function,-Multi-Region,-Local-Cache-support
• If you use the "Run From Zip" deployment method, please take a look at this: sjkp/letsencrypt-siteextension#239 (comment)
• Wildcard domains are not supported, (and will not be supposed in the site-extension), if you are interested in wildcard support check https://github.com/sjkp/letsencrypt-azure
• If you have picked .net core as the runtime on a brand new web site, the extension will not work properly sjkp/letsencrypt-siteextension#349

How to troubleshoot

https://github.com/sjkp/letsencrypt-siteextension/wiki/Troubleshoot

This is Beta Software

Please take note that this Site-Extension is beta-software, so use at your own risk.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYLEFT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Semi-Automated Installation

With the semi-automated installation you manually add the site extension to your web app. Open the extension and manually click through the 3 step dialog.

Once this process is complete your custom domain for the site is setup with a Let's Encrypt issued SSL certificate.

Fully-Automated Installation

To use the Fully Automated Installation the following Web App settings must be added.

Key	Value
letsencrypt:Tenant	The tenant name e.g. myazuretenant.onmicrosoft.com
letsencrypt:SubscriptionId	The subscription id
letsencrypt:ClientId	The value of the clientid of the service principal
letsencrypt:ClientSecret	The secret for the service principal
letsencrypt:ResourceGroupName	The name of the resource group this web app belongs to
letsencrypt:ServicePlanResourceGroupName	The name of the resource group with the app service plan that hosts the web app, if the app service plan is in the same plan as the web app, then this property is optional.
letsencrypt:AcmeBaseUri	The url to Let's Encrypt servers e.g. https://acme-v02.api.letsencrypt.org/directory or https://acme-staging-v02.api.letsencrypt.org/directory (defaults to this)
letsencrypt:Email	The Email used for registering with Let's Encrypt
letsencrypt:Hostnames	Comma separated list of custom hostnames (externally hosted setup with CNames), that should automatically be configured for the site.
letsencrypt:WebRootPath	Use this setting, if you are not serving the website from site\wwwroot, then you can specify the other folder that serves your website here - should be in the format d:\home\site\wwwroot\public or where ever your files are located on the web server.
letsencrypt:DisableWebConfigUpdate	true / false, defaults to false, set this to true if you don't want the site extension to write the default webconfig to wwwroot.well-known\acme-challenge
letsencrypt:SiteSlot	Use this setting if you want to use the extension to setup SSL certificate for deployment slots, the value should be the name of the slot (and the extension should be installed in that slots kudu portal)
letsencrypt:UseIPBasedSSL	Set to true if you want to use IP Based SSL (required by some older clients). Defaults to false, which results in SNI.
letsencrypt:RenewXNumberOfDaysBeforeExpiration	Set to an integer defining the number of days before expiration the certificates should be renewed. Defaults to 22 days before expiration, as letencrypt sends reminder emails 20 days before
letsencrypt:AuthorizationChallengeBlobStorageAccount	(Optional) Set this setting to the connection string of a storage account, if you want to persist the http challenge file to an external azure blob storage, and serve it yourself when let's encrypt request it from the http://yourdomain/.well-known/acme-challenge/{filename} path. (Can be used when local file system cache is enabled or the web app is deployed to multiple region behind traffic manager etc.)
letsencrypt:AuthorizationChallengeBlobStorageContainer	Used in conjuction with letsencrypt:AuthorizationChallengeBlobStorageAccount if you want to specify the name of the container that is used, if not specified then letsencrypt-siteextension is used

As it can be seen from the list of App Settings a service principal is needed. The service principal must be assigned permissions to the web app, that is required as the extension use it for installing and updating the certificate. (If two resource groups are used, the app service principal must have access to both).

Besides the App Settings, the two Azure Web Job required connection strings AzureWebJobsStorage and AzureWebJobsDashboard must also exists, as the extension relies on an internal Web Job to renew the certificates once they expire.

To see an example of an ARM template installation look at azuredeploy.json

github-move's Issues

Preparing the project for Git

Step 2: Prepare the project

Working with Binary files

In general, there are two types of files: text files and binary files.

Text files, like most code files, are easily tracked with Git ^📖 and are very lightweight.

However, binary files like spreadsheets, presentations with slides, and videos don't work well with Git. If your repository already has some of these files, it's best to have a plan in place before you enable Git version control.

You could choose to remove the binary files, or use another tool like git-lfs (Git Large File Storage). We won't get into detail on how to set up git-lfs in this course, but we will talk about .gitignore files next, which are key to protecting your code from becoming bloated with binaries.

Add a .gitignore

As we convert your project to a Git repository, it should only include the source code necessary to build or compile your project. In addition to avoiding binaries as we discussed above, you will also want to keep build artifacts out of your version controlled code.

To do this, you will create a file in your current project named .gitignore. Git will use the .gitignore to determine which files and directories should not be tracked under version control. The .gitignore file is stored in your repository in order to share the ignore rules with any other users that interact with the repository.

Since the files to be ignored are dependent on the language you are using, the open source community has contributed some great templates for .gitignore files in the github/gitignore repository.

⌨️ Activity: Prepare your repository

1. Remove any binary files from your repository.
2. In your local environment, create a .gitignore file. You can use a template or create your own.

When you are finished, close this issue. I will open a new issue with the next steps. 🎉

---

Watch below for my response

🤖 I'm waiting for you to close this issue before moving on.

Public or private repository?

Step 3: Private or Public?

You have one more decision to make before you migrate your code! Right now, your repository is set to public.

You can change the visibility of a repository to Private or Public at any time in your repository's Settings tab, but there are some things you should know.

Private Repositories

If your repository is private, the only people who can see your code are you and the collaborators ^📖 you've invited.

Public Repositories

In public repositories, anybody can see your code. Millions of open source repositories on GitHub are public, too!

Licenses, code of conduct, and other files are important when you create a public repository. There are many benefits to this, but it's also a large responsibility. Keep in mind that once a repository is public and open source, there are certain implications about keeping it public, depending on the license chosen.

It's important to note that public does not equal open source! The license associated with code determines whether or not it is open source.

When you are finished, close this issue. I will open a new issue with the next steps. 🎉

---

Watch below for my response

🤖 I'm waiting for you to close this issue before moving on.

Plan the move

Step 1: Plan the migration

Migrating your repository to GitHub gives you the feature-rich tools and collaboration needed to elevate your project to the next level. This course will guide you through the necessary steps to migrate your repository from another version control system to GitHub.

I know some people like to get straight to the point while others like more information. For those who like more information, be sure to check out the drop-downs like this one ⬇️

Why move to GitHub?

---

Why move to GitHub?

You may be wondering what this GitHub thing is all about and why you should use it. If this sounds like you, here are a few reasons to make GitHub your project's new home:

• Version control — Everything on GitHub is stored in Git, the best version control system around. Version control allows you to experiment and make mistakes in code without messing up your final product.
• Keep your code in one place — Whether you work on multiple computers or just want to get some important projects off your computer, GitHub is the perfect place to store your projects online.
• Collaboration — Once your code is on GitHub, you can invite others to work on your code with you, share it with the world, or send a link to a friend to help you debug a problem.

---

Important considerations for migrations

If you are moving from another version control system such as Mercurial, Subversion, or another Git platform, you will need to make a few decisions:

1. Do you need all of the history?
2. Is there project data that lives outside of the history you need to preserve? (ex: Issues, Discussions, Pull Requests)

Should you keep all of the history?

If you are moving your project to GitHub as a public project, you may want to consider what is in your history. For example:

• Is there sensitive information in historical commit ^📖 messages?
• Do you want to use private email addresses on GitHub?

If ...	Then ...
If you do want to keep the history	Check out the Using the GitHub Importer section under Next steps.
If you do not want all of this history	We recommend you do a clean cutover to "restart" version control and remove any unwanted history. If this sounds like the right option for you, check out the Doing a clean cutover section under Next steps.

Should you keep non-Git data?

Mapping users, keeping commit comments, and other data migrations are more complex, but not impossible. For most version control systems there are helpful Open Source ^📖 tools available. Here are a few resources:

• GitHub's documentation on importing from other VCS
• Blog post about GitHub Migrator tool

Other scenarios

Your project is on another site not using version control, such as CodePen or Glitch

---

Moving your project from another site not using version control

If you are moving your project from a site not using version control, such as CodePen or Glitch, the steps are a bit different that migrating your project from a source that is using version control. Because of this, we have a dedicated course for uploading your local project to GitHub. If this is your situation, please join the Uploading your local project to GitHub course to learn how to handle your case.

---

Your project is already on your local machine

---

Your project is already on your local machine

✨ Terrific! @Joey40 since you already have the project locally, you are almost ready to move it to GitHub.

But, this course guides you through the necessary steps to migrate your repository from another version control system unto GitHub. Since your project is already on your local machine, you need slightly different instructions. Please join the Uploading your local project to GitHub course to learn how to handle your case.

---

⌨️ Activity: Next steps

Choose the drop-down below that best fits your current situation.

If you don't have a repository to use for this activity, you are welcome to use this one: https://github.com/githubtraining/github-move

Using the GitHub Importer

---

Using the GitHub Importer

GitHub has a terrific import tool that will allow you to import your repository in just a few minutes.

First, let's make sure your repository ^📖 is Git friendly. Close this issue and I will open a new issue with next steps.

---

Doing a clean cutover

---

Doing a clean cutover

To do a clean cutover, you will need to remove the existing history. Some people like to save a back up of the project with the history. To start the process:

1. Download a copy of the project to your local machine.
2. Remove version control (with Git this is as simple as running rm -rf .git inside the repository).
3. Now that your project is local on your machine and you have removed any history being tracked by Git, the remaining steps in this course largely cover migrating that Git history. Since you just removed that aspect of your project, please join the Uploading your local project to GitHub course to see the next steps to upload your local project to GitHub.

---

Migrating non-Git data

---

Migrating non-Git data

These migrations are more nuanced and outside the scope of this course. I recommend you go through these steps with a simple repository so you can learn best practices and then apply them to your more complex migration.

---

Ready to move on?

Close this issue to signal you are finished with this step. I will open a new issue to show you how to optimize your repository for Git operations. 🎉

---

Watch below for my response

🤖 I'm waiting for you to close the issue before moving on.

Sometimes I respond too fast for the page to update! If you perform an expected action and don't see a response from me, wait a few seconds and refresh the page for your next steps.

Importing your project

Step 4: Complete the Import

It's time for the big move! Since your source code is in Subversion, Mercurial, Team Foundation Server, or another Git repository, you can move it to GitHub using GitHub Importer. GitHub Importer doesn't bring over every piece of data, but it does bring the history. You can read more about GitHub Importer's capabilities here.

⌨️ Activity: Import your project using GitHub Importer

1. Copy the URL for your existing repository on Subversion, Mercurial, TFS, or another Git server
2. Navigate to the Code tab of this repository and scroll down to the section labeled …or import code from another repository
3. Click Import code
4. Paste the URL for your repository in its current location
5. Click Begin import

Pro-tip, since this repository is empty, you can also import by simply going to: https://github.com/Joey40/github-move/import

---

Watch below for my response

🤖 Once I see you have pushed your project to GitHub, I'll close this issue