Skip to content

Latest commit

 

History

History
298 lines (207 loc) · 13 KB

launch.md

File metadata and controls

298 lines (207 loc) · 13 KB
Raw

GitPitch Enterprise Launch

Verify 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 week ago   1.07GB

Prepare Test Config

The enterprise server runtime depends on an external configuration file, called gitpitch.conf. This is the primary configuration file for the server. Among other things, the properties in this file are used to configure the API endpoints for your self-hosted Git server.

For initial testing purposes use the following test configuration that will communicate with Github.com. We will mirgate from this testing configuration to a 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.

Prepare Test Logging

The enterprise server runtime depends on an additional external configuration file, called gitlog.xml. This file configures the logging policy of the server.

<configuration>

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

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

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

  <root level="WARN">
    <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.

For testing purposes this initial log configuration simply directs logging to standard out. Those logging statements will be displayed in your Docker launch console. While this is a reasonable log configuration for testing purposes, when you are ready we provide production ready log configuration here.

Prepare Volume

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

In preparation for launch, copy the test config and test logging files 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.

Test Launch Server

To launch the enterprise server using the current test configuration, execute the following command in your local shell:

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 just prepared.

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

[info] c.g.g.GRSManager - GIT: GRS[ GitHub ][ github ]
[info] c.g.s.g.ProService - TOKENS: activated=false
[info] c.g.s.g.ProService - JVM: processors=2, max memory=1908932608
[info] play.api.Play - Application started (Prod)
[info] p.c.s.NettyServer - Listening for HTTP on /0.0.0.0:9000
[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 report any logging output visible in the console.

Verify Test Launch

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

By default, your server responds on localhost:9000. Therefore, to launch the GitPitch Demo Deck open the following URL in any browser on your Linux server:

http://localhost:9000/gitpitch/demo-deck

If you can verify that this 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 on-screen or in the console output.

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

Prepare Prod Config

Earlier we prepared a test config gitpitch.conf 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 the enterprise server 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 endpoint
# for your self-hosted Git server. For most Git server types, these property
# values should be set to the same value. And both values must end in a '/' character.
#
# [Optional]
# Uncomment the `apitoken` property and replace `xxx...` with a Personal Access Token
# for the primary Git account within your organization. If specified, this `apitoken`
# will be used by default on all API calls to your Git server.
#

gitpitch {

  git {
    repo {
      service {
        name        = "your-organization-name"
        type        = "your-git-server-type"
        apibase     = "http(s)://xxx/yyy/"
        rawbase     = "http(s)://xxx/yyy/"
        apitokenheader    = "Authorization"
        # apitoken    = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        gistbase    = "https://gist.githubusercontent.com/"
      }
    }
  }

}

To start this migration, copy the contents of the above configuration block and use it to overwrite the test 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.

Launch Prod Server

To launch enterprise server 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 just prepared. 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

[info] c.g.g.GRSManager - GIT: GRS[ GitHub ][ github ]
[info] c.g.s.g.ProService - TOKENS: activated=false
[info] c.g.s.g.ProService - JVM: processors=2, max memory=1908932608
[info] play.api.Play - Application started (Prod)
[info] p.c.s.NettyServer - Listening for HTTP on /0.0.0.0:9000
[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.

Verify Prod Launch

The best 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 markdown 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 in the root directory.

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.

If you have successfully verified the integration of GitPitch Enterprise with your Git server we strongly recommend the following:

  1. Activate Production Logging for your server.
  2. Relaunch your server using Docker Detached Mode.

Docker Detached Mode

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