-
Notifications
You must be signed in to change notification settings - Fork 6
Installation and Configuration
CaptainHook is designed to be hosted either as a separate ASP.NET application (although the only thing from the ASP.NET stack it uses is the IHttpHandler interface, it’s still technically an ASP.NET application) or as part of another ASP.NET web site/application.
After successfully compiling CaptainHook, copy the contents of the Web/ directory to a directory on your web server which will serve as the root folder of the application. You need to copy the entire App_Data and bin directories and the Global.asax and web.config files – copying of the .cs files is not necessary. After the copy s done, follow the configuration instructions below.
Copy contents of the App_Data directory to your ASP.NET application’s App_Data directory, repeat the same with the contents of the bin directory, putting all the files in it in the bin directory of your application.
If your application already has Global.asax you will most likely need to modify its code behind or the Global.asax file directly (if it contains source code) by copying the code in the Application_Start method from the CaptainHook’s Global.asax.cs to your application’s Application_Start method. If your application uses code-behind compilation model (that is, its source files are compiled to an assembly in the bin/ directory as opposed to model in which your *.as?x files contain the CodeFile attribute) you need to recompile it with CaptainHook’s code in place.
DO NOT copy CaptainHook’s web.config file to your application’s root directory!
After this is done, follow the configuration instructions below.
The first step after deploying CaptainHook to your web server using one of the methods above is to modify the App_Data/CaptainHook.xml file from its default form shown below:
<?xml version="1.0" encoding="utf-8" ?>
<CaptainHook>
<options>
<!-- If present, LogSeverity.Debug messages will be thrown and all logged exceptions will include full stack trace -->
<debug/>
<!-- Directory with templates (physical path). If relative, it is looked up under the directory specified in the ConfigDirectory appSettings entry in web.config -->
<baseTemplatePath value="templates"/>
<!-- If not present, defaults to localhost:25 and no credentials. If you're hosting the handler under Mono and attempts to use SMTPAUTH with TLS fail, please read http://www.mono-project.com/FAQ:_Security#Does_SSL_works_for_SMTP.2C_like_GMail_.3F -->
<smtpServer host="mysmtp.host" port="587" enableSSL="true" user="myuser" password="mypassword"/>
</options>
<!-- Each commit source must have a unique ID -->
<commitSource id="f6ec6290-7143-4d41-a3ae-0b819bab7781" sendAsCommitter="true">
<!-- Required if the 'sendAsCommitter' attribute for the 'commitSource' element is false -->
<!-- If sendAsCommitter is set to true, then the address below (if defined) is used as the envelope sender and the
committer's mail as the From: value header. If <from> is missing, which in this case is allowed, committer's
mail is used for envelope.
If sendAsCommitter is false, the address below is used in both places and is required to be present. -->
<from name="CaptainHook" address="[email protected]" />
<!-- Optional. Defaults to <from> above or to the committer's mail if sendAsCommitter is true -->
<replyTo name="My Mailing List" address="[email protected]" />
<!-- A list of TO recipients -->
<to>
<email name="My Name" address="[email protected]"/>
</to>
<!-- A list of CC recipients -->
<!-- <cc>
<email address="[email protected]"/>
</cc> -->
<!-- A list of Bcc recipients -->
<!-- <bcc>
<email address="[email protected]"/>
</bcc> -->
</commitSource>
</CaptainHook>
The things you need to change are all the email addresses (only the <from> address and at least one in the <to> list are required) and the commit source ID. The commit source ID can be any string as long as it does not contain underscores (_) or dots (.) and is unique among all of your commit sources. You can generate a UUID (GUID in .NET) using the following command line on Linux/Unix:
uuidgen
or on the web by visiting the web-based UUID generator
The only thing you need to do is to edit the web.config file to replace the value of the PosterAuthID key in the <appSettings> section with another UUID (or a unique string following the same set of restrictions as the commit source ID above).
In this case, you need to first copy contents of the <appSettings> section of CaptainHook’s web.config to the <appSettings> section of your application’s web.config file. Then, locate the <httpHandlers> section in your application’s web.config file (or create it if it doesn’t exist) and put the following line near the top of that section:
<add verb="POST" path="*.github" type="CaptainHook.Web.Handlers.GitHubJsonPostHandler, CaptainHook.Web"/>
And that’s it! CaptainHook is configured. Now follow the steps below to configure your GitHub repository to call your CaptainHook every time anyone pushes changes.
In the sections above you generated two UUID values (or two unique strings) – one for the commit source ID and another for poster authorization ID. CaptainHook expects to find those values in the request sent to it by GitHub, but since we don’t have any control over the contents of the request, CaptainHook uses name-based convention to retrieve those values from the URL of the request. The syntax of the URL must follow the format shown below:
http://yourserver.com/somedirectory/authID_commitSourceID.github
Where authID must be replaced with the same value as found in your application web.config file’s <appSettings> section, in the PosterAuthID key and commitSourceID must be replaced with the same value as the one assigned to the commit source id attribute in CaptainHook.xml file. Neither of those two values can contain any underscore (_) or dot (.) characters. CaptainHook ignores the .github extension.
This completes the setup. At this point you can either push a commit to your repository or click the Test Hook button in your repository’s Admin panel (in the Service Hooks section) to see a request sent to your CaptainHook instance and subsequently a mail with the notification delivered to your mailbox.