gitpitch/docs/enterprise/launch.md

# GitPitch Enterprise Launch

- [Verify Docker Image](#verify-docker-image)
- [Prepare Test Config](#prepare-test-config)
- [Prepare Test Logging](#prepare-test-logging)
- [Prepare Volume](#prepare-volume)
- [Test Launch Server](#test-launch-server)
- [Verify Test Launch](#verify-test-launch)
- [Prepare Production Config](#prepare-prod-config)
- [Launch Production Server](#launch-prod-server)
- [Verify Production Launch](#verify-prod-launch)
- [Docker Detached Mode](#docker-detached-mode)

### Verify Docker Image

Following a successful [installation](/enterprise/install), 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:

```console
$ 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.

```yaml
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.

```xml
<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](/enterprise/config).

### Prepare Volume

The enterprise server depends on a [Docker volume](https://docs.docker.com/storage/volumes) 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](#prepare-test-config) and [test logging](#prepare-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:

```tree
├── 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:

```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](https://gitpitch.com/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](#prepare-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.

```yaml
# 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:

```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 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](/conventions/pitchme-md.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.

<hr>

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

1. Activate [Production Logging](/enterprise/config.md) for your server.
1. Relaunch your server using [Docker Detached Mode](#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:

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

For example:

```shell
$ 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:

```shell
docker container ls
```

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

```shell
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:

```shell
docker container stop gitpitch
```