Developer Gateway Installer

From Direct Project
Jump to navigation Jump to search
Back: Setup instructions

Table of Contents

WARNING: VISUAL EDITOR BREAKS KEY LINKS ON THIS PAGE!
  • YOU MUST DISABLE VISUAL EDITOR IN YOUR ACCOUNT SETTINGS BEFORE EDITING. SWITCHING out of Visual Edit still breaks links


Overview

The developer setup installs the Direct for a single developer machine. The goal is to let you, the developer, create an installation to learn how the system works and pieces fit together. The installation is not a toy. You can use it to send and receive real Direct messages on the public Internet. All the components you would run in production also run here - except on a single machine, and with safe developer settings by default. 
 
  The developer install gives you a template from which you can derive your production deployment scripts or MSIs tailored to your operational needs. The developer installation is meant to show you the way. Your production deployments will use the same components and binaries, but place them in different folders, on different machines, with different configuration settings.

Requirements


Installer

You are strongly encouraged to read the documentation below'.'
  • You may need to customize some settings if you don't use the defaults.
    • Typically, only database connection strings.
  • The docs should help in getting your system running and with trouble-shooting
    • If you see errors in the documentation, please fix them, but please do not use the Visual Wiki Editor.
    • If you think more docs are needed or have thoughts that could help others, please capture on a Wiki page.
  • Your efforts to diagnose your own system and getting it running are truly appreciated !!



Download

You can get the last official release here: codebetter.com 
 
  Current Stable Release: 1.2.0.45
  • Full Gateway
  • Middle Tier
  • Dns Server
  • Admin Tools
  • Latest bug fixes



Next planned release: In the next couple months.

  • XD* [Planning release date]
  • Policy [No release date. Research mode. ]


Limitations

  • Requires 64 bit Windows - x64 architecture.
    • The reference implementation will run on 32 bit Windows, but currently there is no installer support
  • The Installer is most reliable if you use all the Default settings
  • Single Box install when selecting "Developer Install" at the installer
    • Database Connection strings in config files created by the Installer assume:
      • You are running SqlExpress on your machine
      • You are accessing it using Integrated Security=SSPI;
    • If you use full Sql Server, a different database or specific Logins:
      • You can manually edit connection strings in a couple of config files.
      • Fortunately, this is pretty easy, and Direct configuration settings are documented in detail.
      • The installer also allows the connection string to be configured and tested. Of course if you are using Integrated Security=SSPI; the user executing the installer is the Windows User being tested.


What you get

Components

  • Direct Gateway
  • Middle Tier Config Services
  • Direct Dns Server
  • Command Line Admin Config Console
  • Admin Web UI


Sample Configuration when selecting "Developer Install"

Setup automatically creates and installs exemplar domains, addresses, certs and anchors. You get:
  • 2 test email domains - currently the same ones used by the C# Unit Tests:
    • redmond.hsgincubator.com
    • nhind.hsgincubator.com
  • 2 email addresses:
    • toby@redmond.hsgincubator.com
    • biff@nhind.hsgincubator.com
  • Organizational Certificates and Private Keys for both domains
  • Anchors set up for mutual trust between domains
  • Dns records pre-created and ready to be served by the Direct Dns Server
  • And so on...


Once you see how that works, you should be able to easily customize the deployment for your own domains and addresses and start exchanging messages with other Direct nodes.

Note: The default developer configuration prevents messages from being put on the wire until you explicitly enable the feature. This ensures you do not accidentally send spam - unless of course you wanted to.

Location of Binaries and Config Files

By default, the installer places all binaries and configuration files in C:\Program Files\Direct Project .NET Gateway.
 
  In the rest of the document, we'll refer to the installation directory as $InstallDir.

First Time Installation


There are two paths to take. Install the "Developer Install" as indicated by the selection in the image below or install the components individually. To see examples of installing individual components see the Enterprise Installation Instructions.

SelectDeveloperInstall.png


After copying binaries, Installer will present you with this screen.

  • It is important that you CHECK ALL OPTIONS otherwise the system will not work out of the box
  • You can be more choosey when you install updates OR get familiar with the workings.


Installer.png

Microsoft Visual C++ Redistributable Package


The VC++ runtime is used by $InstallDir\SmtpEventHandler.dll. This is the small native 64 bit DLL used to hook SMTP Server events. The Dll then invokes the actual .NET SmtpAgent code in $InstallDir\Health.Direct.SmtpAgent.dll. The Enterprise Installation does not provide the runtime check box if it is already installed.

If you already have the right VC Redistr installed on your machine, Setup will ask you if you want to Repair or Remove the installation.

  • Select Repair.


Install Database

Installs the Direct Database. The installer will ask for the following:
  • Server/Instance Name
  • User Name and Password
  • Database Name

Server Instance

  • ====Default: .\SqlExpress====
  • To use a full database server, type the machine name
  • Note: if you don't use SqlExpress, you must hand-edit connection strings


User Name and Password

The installer uses the user name and password to connect to the database server and create the database. 
 Default: Uses your Windows Credentials.
 
 The user name you supply must have db-creator permissions.

Database Name

Default: DirectConfig. Use the default name.

Errors

Database creation errors will typically be caused by permissions problems. 
  Worst case, you can create the database manually after the rest of the installation completes (see Post-Installation steps)

Install Gateway

Installs the following:
  • Direct Gateway
  • Direct Middle Tier
  • Direct Dns Server
  • Admin Tools


If there are errors during installation (such as Powershell grumblings), you can complete some steps manually (below).

Post-Installation Steps


Manual Installation

In case of error, you can recreate most of what the installer does by hand.
  • Notepad C:\Program Files\Direct Project .NET Gateway\install-dev.bat
  • Steps for manual database creation are below



Direct Database

The Direct Gateway stores domains, addresses, certificates, anchors and Dns records in a Sql Database.
  • The installer automatically creates the database and all associated indexes for you.
  • You will need to set up Sql Logins and permissions yourself


Creating Database Manually

In case of an error, you can also create the database manually.
 
  The installer places 2 SQL scripts in $InstallDir\Sql
  • Schema.sql
  • CreateUser.sql
  1. Connect to your Database using your Admin tool
  2. Manually create a database named DirectConfig [DO use this name]
  3. Run Schema.sql
  4. Assign Users/Logins appropriately
  5. Make sure you update connection strings appropriately

Middle Tier

The installer creates 2 applications under your local IIS web server's DefaultWebSite.
  If you move the applications or give them different Urls, you will need to manually configuration settings for:
  • Direct Gateway
  • Direct Dns Server

ConfigService

The ConfigService provides middle tier CRUD access to the Direct database.

Binaries and Source

The installer places source in $InstallDir\ConfigService

Configuration Settings

  • $InstallDir\ConfigService\Web.config
  • Settings Documentation
    • You should only need to customize the connect string.
  • If you edit the file, you should recycle the Application Pool or IISRESET

Application Pool

By default, the ConfigService runs in the DefaultAppPool.

Database Connectivity

The ConfigService requires read/write access to the Direct Database.
  • To verify database connectivity: [1]
  • If your connection strings contain Integrated Security=SSPI, you must run the Application Pool with a User Account that can has read/write access to the database.
    • E.g. Network Service
  • If you customize connection strings, make sure they are correct.

WCF Working

The ConfigService is a WCF service.
  • To verify that you have WCF correctly installed: [2]

Log Files

By default, log files are written to $InstallDir\ConfigService\Log
  You can customize logging by changing the config file.

DnsService (Middle Tier)

The DNS Middle Tier provides read-only access to Dns Records. The Direct Dns Server, which implements the DNS protocol, uses the middle tier as its Dns record store - and retrieves records by calling the middle tier.

Binaries and Source

The installer places source in $InstallDir\DnsService

Configuration Settings

  • $InstallDir\DnsService\Web.config
  • Settings Documentation
    • You should only need to customize the connect string.
  • If you edit the file, you should recycle the Application Pool or IISRESET

Application Pool

By default, the DnsService runs in the DefaultAppPool.

Database Connectivity

The DnsService requires read/write access to the Direct Database.
  • To verify database connectivity: [3]
  • If your connection strings contain Integrated Security=SSPI, you must run the Application Pool with a User Account that can has read/write access to the database.
    • E.g. Network Service
  • If you customize connection strings, make sure they are correct.

WCF Working

The ConfigService is a WCF service.
  • To verify that you have WCF correctly installed: [4]

Log Files

By default, log files are written to $InstallDir\DnsService\Log
  You can customize logging by changing the config file.

Direct Gateway

By default, the Developer Direct Gateway will not relay either incoming or outgoing messages - to prevent accidental spam. It is configured to drop outgoing and incoming messages into folders on your drive.
 
 You must explicitly Enable Message Relay.

Binaries and Source

The installer places binaries, config files and scripts in $InstallDir.

Configuration Settings

  • $InstallDir\DevAgentConfig.xml
  • Settings Documentation
  • You will need to customize settings if:
    • You are not running the Middle tier on the local machine or with the default Urls.
    • You want to Enable Relay - i.e. tell the Gateway to actually put mail on the wire
    • Create your own domains
  • If you change configuration, restart Smtp Service.

Log Files

By default, log files are written to $InstallDir\Log
  You can customize logging by changing the config file.

Verify Domains are Registered in Middle Tier

You should only need to do this if there was an error during installation.
  • Launch a command prompt
  • cd to $InstallDir
  • run ConfigConsole.exe
  • type domain_list
    • If you get an error verify that ConfigConsole.exe is properly configured to access the middle tier (below)
  • If no domains were listed, run domain registration manually:
  • type batch setupdomains.txt

Verify Addresses are Registered

  • Run ConfigConsole.exe
  • type address_list redmond.hsgincubator.com
  • type address_list nhind.hsgincubator.com


Adding Test Domains To SMTP Server

The Developer Gateway comes preconfigured to run the following test domains:
  • redmond.hsgincubator.com
  • nhind.hsgincubator.com


These are the same domains used by the C# unit tests. The installer automatically installs test certificates and anchors for these domains.

You can view the domains in the Gateway Configuration file:

  • Open $InstallDir\DevAgentConfig.xml in Notepad

You should see:

<SmtpAgentConfig>
    <Domain>redmond.hsgincubator.com</Domain>
    <Domain>nhind.hsgincubator.com</Domain>


Add both domains to Smtp Server with the SmtpServer Admin User Interface.

  • **This is required.
  • It will allow you to send some simple messages immediately and learn how to operate the system
  • You can subsequently create your own certificates, anchors and domains...


Automating Smtp Server Configuration

You can also automate Smtp Server setup by using the IIS 6.0 Programming model.
[File:http://www.wikispaces.com/i/mime/32/text/plain.png createsmtp.vbs]

Restarting Smtp Service

From the command line:
    • IISRESET
    • OR:
      • net stop smtpsvc
      • net start smtpsvc


Set Smtp Service to Start Automatically

By default, the Smtp Service does not automatically restart after reboots.
  • Go to the Services Control Panel
  • Find and set the Smtp Service to start Automatically


Config Console

ConfigConsole.exe is a command line tool you use to manage your Direct Gateway. It invokes the Middle Tier Config Service to manage:

  • Domains
  • Address
  • Certificates
  • Private Keys
  • Anchors
  • Dns Records

Binaries and Source

The installer places binaries and config files in $InstallDir.

Configuration Settings

The ConfigConsole works with the WCF Middle Tier and needs Urls to these services.

Sample Usage

  • Go to $InstallDir
  • Open setupdomains.txt in Notepad


You can run a "batch" of commands by typing:
ConfigConsole.exe batch [textFilePath]

Direct Dns Server

The Direct Dns Responder Service is a Windows Service. 
  It implements the DNS protocol and listens for DNS requests on both UDP & TCP Port 53. 
 
  In addition to serving up the usual ANAME, MX, CNAME and NS records, the server dynamically returns DNS CERT records. You do not need to do any special configuration of CERT records - the server is designed to return any Certificates you installed into the Config System automatically.
 
  To run DNS:


The Server retrieves DNS records from the Dns Server middle tier.

Starting and Stopping

You manage the server using the standard Services UI or the command line:
  • net start directdnsrespondersvc
  • net stop directdnsrespondersvc

Binaries and Source

The installer places binaries and config files in $InstallDir.
  • DirectDnsResponderSvc.exe


You can manually install/uninstall the service using the .NET Framework tool: installutil.exe

Configuration Settings

  • $InstallDir\DirectDnsResponderSvc.exe.config
  • Settings Documentation
  • If you change Settings, you will need to restart the service

IP Addresses and Ports

  • The developer answers requests only on the localhost (127.0.0.1) IP address.
<DnsServerSettings Address="127.0.0.1" Port="53" DefaultTTL="3600">


You can change this configuration to listen on any IP addresses on your machine. 0.0.0.0 is a special reserved IP address called Any.

    <DnsServerSettings Address="0.0.0.0" Port="53" DefaultTTL="3600">
      <UdpServerSettings MaxOutstandingAccepts="4" MaxActiveRequests="64" SendTimeout="10000" ReceiveTimeout="10000"/>
      <TcpServerSettings MaxOutstandingAccepts="4" MaxActiveRequests="64" SendTimeout="10000" ReceiveTimeout="10000" SocketCloseTimeout="2000"/>
    </DnsServerSettings>


Adding Dns Records

Verifying DNS

The developer installation does not create any standard DNS records like MX. But it will automatically return CERTIFICATES installed in your Config Service as CERT records.

[[CSharp+Setup+Instructions#DNS|Configuring DNS]]
Retrieved from "https://directproject.mywikis.wiki/w139/index.php?title=Developer_Gateway_Installer&oldid=216"