Skip to content

Latest commit

 

History

History
64 lines (40 loc) · 4.13 KB

ADAPTING.md

File metadata and controls

64 lines (40 loc) · 4.13 KB
Raw

How to Adapt this Project

If you find the below instructions confusing or unhelpful in any way, please let us know by opening an issue. We'd be happy to help you work through the instructions to make use of this project!

Step 1: Fork or Clone this Repository

You'll want a copy of this repository so that you can edit it and adapt it for your needs. This can be done by either:

  • Forking the repository to your own organization / account
  • Downloading a copy of this source code and then uploading it to a repository under your account.

Forking will allow you to receive upstream updates, but over time those updates may conflict with the changes you plan to make on your own. We recommend forking, at least to start -- you can pull in the changes that suit you, and even contribute back if you do something cool with the project!

Step 2: Set up a Google Analytics Account

This site is designed to work with Google Analytics, so if you set up a GA account, you'll be able to track all of the hits and origins of those who are using your short links. It's also possible to check which links people are looking for that aren't found, etc. in order to gain more insight.

Once you sign up for Google Analytics, you'll want to setup a tracking property.

Step 3: Modify the Settings

In the src/xluhco.web directory, you'll find a file called appsettings.json.

In this file, you'll want to update:

  • TrackingPropertyId: Update this with the tracking property that you got when you created the Google Analytics for your site. If you leave it set to the default, we'll receive all of your hits and it will confuse us. :)
  • ShortLinkUrl: This is the URL where you've chosen to host your link shortener -- your equivalent of xluh.co, aka.ms, bit.ly, etc. It will prefix all of your short links throughout the app, show up in the title bar and on the home page, etc.
  • CompanyName: The name of your company. Shows up on the home page, etc.
  • CompanyHomePageUrl: Your company's web site. This link shows up on the home page.
  • InstrumentationKey: If you choose to use AppInsights, you'll want to replace this with your own key so it isn't confused with ours.

Step 4: Set up Continuous Integration

This application uses Azure DevOps Pipelines out of the box. We supply an azure-pipelines.yml file that should have all of the settings & steps necessary to create a CI build from your source code for every one of your own changes. This ensures you'll know the app works if you make any other changes to it.

If you sign up for Azure DevOps and point it to your cloned repository, the azure-pipelines.yml file should take care of most of your work.

Step 5: Set up a Deployment Pipeline

In the case of the live xluh.co domain, we use an Azure Web Site and Azure DevOps Releases to automatically deploy from our main branch. You can do this via the steps below.

Creating the Site

  • Log into Azure. Create a subscription if you haven't already
  • Create a new .NET Core web site (if you haven't already)

Creating the Release

  • Log into Azure DevOps
  • Navigate to the project you created in the previous step for the build
  • Click Releases
  • Create a Release
  • Select the artifact from the build as the basis for the release
  • Filter the release to the master branch or the name of your main branch.
  • For the release task, select deploying to an Azure Web App
  • Select the web app you previously created
  • Ensure that the release is set to automatically kick off.
  • Save your changes

After this, you'll have a web site that deploys automatically, and a CI process that protects your code before it makes it to the main branch. Not bad!

Step 6: Update the docs (Optional)

The URLs in this document are not relative -- so the "submit an issue" links, etc. will always point to the http://github.com/excellalbas/xluhco repository, even after you fork them. You may wish to edit these markdown files in your repository to update them with your project's URL instead.