Launch GitPitch Enterprise



Step 1. Verify GitPitch Enterprise Docker Image

Following a successful installation, the GitPitch Enterprise image should be visible to Docker on your local server. You can verify the presence of the image using the following command:

docker images

The output generated by that command should confirm the existence of your local copy of the GitPitch Enterprise image. The output should be similar, but not necessarily identical, to the following:

$ docker images

REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
gitpitch/enterprise          latest              83447a6c80d6        1 day ago         199MB


Step 2. Prepare GitPitch Server Test Configuration

The GitPitch Enterprise runtime depends on an external configuration file, called gitpitch.conf.

This is the primary configuration file for the GitPitch server. Among other things, the properties in this file can be used to configure the API endpoints for your self-hosted Git server.

At this stage we are going to use a fixed configuration - that communicates with github.com - for initial testing purposes only. We will mirgate from testing to production configuration later in this guide.

include "application.conf"

gitpitch {
  git {
    repo {
      service {
	name        = "GitHub"
	type        = "github"
	apibase     = "https://api.github.com/"
	rawbase     = "https://api.github.com/"
	gistbase    = "https://gist.githubusercontent.com/"
	apitokenheader    = "Authorization"
      }
    }
  }
}

For now, simply copy the contents of the above configuration block without modification. Save those contents to a file named gitpitch.conf on your Linux server. The small icon in the top-right of the block provides a convenient one-click copy to your clipboard.


Step 3. Prepare GitPitch Server Log Configuration

The GitPitch Enterprise runtime depends on an additional external configuration file, called gitlog.xml. This file configures the log behavior of the GitPitch server.

<configuration>

  <conversionRule conversionWord="coloredLevel"
                  converterClass="play.api.libs.logback.ColoredLevel" />

  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>/data/gitpitch-server-testing.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>/data/gitpitch-server-testing.log-%d{yyyy-ww}</fileNamePattern>
      <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
      <pattern>%date %coloredLevel %logger{15} - %message%n%xException{10}</pattern>
    </encoder>
  </appender>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%date %coloredLevel %logger{15} - %message%n%xException{10}</pattern>
    </encoder>
  </appender>

  <appender name="ASYNCFILE" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="FILE" />
  </appender>

  <appender name="ASYNCSTDOUT" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="STDOUT" />
  </appender>

  <logger name="com.gitpitch" level="INFO" additivity="false">
    <appender-ref ref="ASYNCFILE" />
    <appender-ref ref="ASYNCSTDOUT" />
  </logger>

  <logger name="play" level="INFO" />

  <root level="WARN">
    <appender-ref ref="ASYNCFILE" />
    <appender-ref ref="ASYNCSTDOUT" />
  </root>

</configuration>

For now, simply copy the contents of the above configuration block and save it to a file named gitlog.xml on your Linux server. The small icon in the top-right of the block provides a convenient one-click copy to your clipboard.

This initial log configuration will result in the following logging behavior by the GitPitch server:

  1. Log statements are written to standard out and displayed in your Docker launch console.
  2. Log statements are written to a file called gitpitch-server-testing.log in your Docker volume directory.

While this is a reasonable log configuration for testing purposes, we recommend disabling the writing of log statement to standard out in production. For your convenience, we provide a sample production ready log configuration here.

Note, the Docker volume directory referred to above is described in detail in the next section.


Step 4. Prepare Docker Volume Directory

GitPitch Enterprise depends on a Docker volume at runtime. This volume provides a mechanism for the live GitPitch Enterprise container to read and write files on the host file system of your Linux server.

In preparation for launch, please copy the configuration files created during step 2 and step 3 into your chosen Docker volume directory. Your chosen directory should be dedicated exclusively for use by GitPitch Enterprise.

After copying the required configuration files, the contents of the directory should look as follows:

├── gitpitch.conf
|── gitlog.xml

Note, these file names are case-sensitive. The files indicated must be present in your Docker volume directory before moving on to the next step.


Step 5. Test Launch GitPitch Enterprise

To launch GitPitch Enterprise using the current test configuration, execute the following command:

docker run --rm -it -v {DVD}:/data -p 9000:9000 gitpitch/enterprise:latest

Note, {DVD} is a placeholder. You must replace it with an absolute path to the root of the Docker volume directory you prepared in step 4.

For example, assuming /Users/david/gpe is your chosen Docker volume directory, then the full launch command would be as follows:

docker run --rm -it -v /Users/david/gpe:/data -p 9000:9000 gitpitch/enterprise:latest

Following this launch command you should expect to see a small amount of console output, like this:

$ docker run --rm -it -v /Users/david/gpe:/data -p 9000:9000 gitpitch/enterprise:latest


2018-06-12 09:36:30,116 [info] play.api.Play - Application started (Prod)
2018-06-12 09:36:30,315 [info] p.c.s.NettyServer - Listening for HTTP on /0.0.0.0:9000
2018-06-12 09:36:30,319 [info] p.c.s.NettyServer - Listening for HTTPS on /0.0.0.0:9443

If your console output is similar to that shown above, please move on to the next step. Otherwise, please get in touch and provide details of any failures you are seeing. To aid the debugging process, please attach the gitpitch-server-testing.log log file that has been written to the root of your Docker volume directory.


Step 6. Verify Test Launch GitPitch Enterprise

The simplest way to test your GitPitch Enterprise server instance is to open a slideshow presentation in your browser and verify that it is rendered correctly.

By default, your GitPitch Enterprise server responds on localhost:9000. Therefore, to launch the GitPitch Hello World sample presentation - found in the gitpitch/kitchen-sink repository on GitHub - open the following URL in any browser on your Linux server:

http://localhost:9000/gitpitch/kitchen-sink

If you can verify that the sample presentation opens and renders correctly in your browser, move on to the next step. Otherwise, please get in touch and provide details of any failures you are seeing.


Before moving on to the next step, please stop your test GitPitch Enterprise container by typing Ctrl-C in the console window where you launched the instance.


Step 7. Prepare GitPitch Server Production Configuration

Earlier in step 2 we prepared a gitpitch.conf server configuration file for initial testing purposes. In this step will need to migrate from that testing configuration to your production configuration.

The production configuraiton will activate the integration between GitPitch Enterprise and your self-hosted Git server.

# The following include statement is required.
include "application.conf"

#
# [Required]
# Update the `name` property value to match the name
# of your Organization.
#
# [Required]
# Update the `type` property value to match the
# type of self-hosted Git server used by your Organization.
#
# The value set on the `type` property value must be
# one of the following:
# github, gitlab, bitbucket, gitbucket, gitea, gogs
#
# [Required]
# Update the `apibase` and `rawbase` property values to match
# the API endpoints for your self-hosted Git server.
#
# [Optional]
# Uncomment the `apitoken` property and replace `xxx...` with a
# GitHub Personal Access Token for the primary GitHub user
# account within your organization.
#

gitpitch {

  git {
    repo {
      service {
        name        = "organization-name"
        type        = "git-type"
        apibase     = "https://domain-port/"
        rawbase     = "https://domain-port/"
        gistbase    = "https://gist.githubusercontent.com/"
        apitokenheader    = "Authorization"
        # apitoken    = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }

}

To start this migration, copy the contents of the above configuration block and use it to overwrite the current contents of the gitpitch.conf on your Linux server. The small icon in the top-right of the block provides a convenient one-click copy to your clipboard.

Next, make changes to the configuration property values in that file by following each of the instructions marked [Required] in the comments. When your gitpitch.conf file has been updated to reflect your specific configuration, please move on to the next step.


Step 8. Launch GitPitch Enterprise

This step uses the same launch commands introduced in step 5.

To launch GitPitch Enterprise using your new production configuration execute the following command:

docker run --rm -it -v {DVD}:/data -p 9000:9000 gitpitch/enterprise:latest

Note, {DVD} is a placeholder. You must replace it with an absolute path to the root of the Docker volume directory you prepared in step 4.

For example, assuming /Users/david/gpe is your chosen Docker volume directory, then the full launch command would be as follows:

docker run --rm -it -v /Users/david/gpe:/data -p 9000:9000 gitpitch/enterprise:latest

Following this launch command you should again expect to see a small amount of console output, like this:

$ docker run --rm -it -v /Users/david/gpe:/data -p 9000:9000 gitpitch/enterprise:latest


2018-06-12 09:36:30,116 [info] play.api.Play - Application started (Prod)
2018-06-12 09:36:30,315 [info] p.c.s.NettyServer - Listening for HTTP on /0.0.0.0:9000
2018-06-12 09:36:30,319 [info] p.c.s.NettyServer - Listening for HTTPS on /0.0.0.0:9443

If your console output is similar to that shown above, please move on to the next step. Otherwise, please get in touch and provide details of any failures you are seeing.


Step 9. Verify Launch GitPitch Enterprise

Again, the simplest way to test your GitPitch Enterprise production server instance is to open a slideshow presentation in your browser and verify that it is rendered correctly.

Now that you are using your production configuration, GitPitch Enterprise is communicating with your self-hosted Git server. Therefore, at least one repository on that server needs to contain a PITCHME.md file for verification purposes.

Open the following URL in any browser on your host Linux server:

http://localhost:9000/{user}/{repository}

Note, both {user} and {repository} are placeholders. You must replace them with a valid user account and repository name on your self-hosted Git server. And that repository must contain a PITCHME.md markdown file.

If you can verify that the sample presentation opens and renders correctly in your browser, congratulations - GitPitch Enterprise has been successfully integrated with your self-hosted Git server. Otherwise, please get in touch and provide details of any failures you are seeing.

Following a successful launch you may want to consider activating Production Logging for your server.


Appendix - Interactive v Detached Mode Launch

All of the sample launch commands above demonstrate the starting of the GitPitch Enterprise container in interactive mode, using the -it flag on the launch command.

Interactive mode makes it very simple to stop a live container using nothing more than a Ctrl-C in the launch console window. This approach makes sense for testing purposes.

In a real production environment, the GitPitch Enterprise container should be launched using detached mode. Using detached mode ensures the server is run in the background.

Launching GitPitch Enterprise using detached mode is achieved as follows:

docker run --name gitpitch --rm -d -v {DVD}:/data -p 9000:9000 gitpitch/enterprise:latest

For example:

$ docker run --name gitpitch --rm -d -v /Users/david/gpe:/data -p 9000:9000 gitpitch/enterprise:latest

96ee5f19d6339601c78e248f36e38aa1563fdbd0b6393343175593a9e601b01d

As shown above, following the execution of this command the long container ID for your GitPitch Enterprise container instance is output to the console. At this point, the container is running in the background.

You can also lookup the abbreviated container ID using the following command:

docker container ls

You can use the long or abbreviated container ID to terminate the background container process. For example:

docker container stop 96ee5f19d633

Alternatively, if you named the container using the name syntax at launch, you can also terminate the background container by name:

docker container stop gitpitch