Skip to content

Commit daf4652

Browse files
rosieyohannanrosieyohannan
committed
Merge branch 'add/windows-server-newerer' of github.com:circleci/circleci-docs into add/windows-server-newerer
2 parents aa5adc1 + 3e5bb04 commit daf4652

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+713
-42
lines changed

‎README-server-docs.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Then, from the top of the circleci-docs directory, run:
2121

2222
You will then find the PDFs in: `releases/tmp`
2323

24-
This script is run as part of the CCI build everytime you push a commit, then the PDFs can be found in the build artifacts, accessible from the CircleCI UI.
24+
This script is run as part of the CCI build every time you push a commit, then the PDFs can be found in the build artifacts, accessible from the CircleCI UI.
2525

2626
## Some notes about formatting
2727

‎docs/Content-Reuse.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Reusable Content
2-
If content is to be used in multiple locations throughout the documentation, it may be benefitial to convert the content to either of the following:
2+
If content is to be used in multiple locations throughout the documentation, it may be beneficial to convert the content to either of the following:
33

44
* A snippet - suitable for a section of text or code block that needs to appear in more than one location.
55
* A site variable - suitable for a small amount of information, for example a version number or single word.

‎jekyll/_cci2/admin-faq.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
This chapter answers frequently asked questions and provides installation troubleshooting tips.
911

1012
toc::[]

‎jekyll/_cci2/architecture.adoc

+4-2
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
//:circle-warning: image:circle-warning.png[]
99
//:circle-failure: image:circle-failure.png[]
1010

11+
{% include snippets/server-only.adoc %}
12+
1113
This document outlines the containerized services that run on the Services machine within a CircleCI Server installation. This is provided both to give an overview of service operation, and to help with troubleshooting in the event of service outages. Supplementary notes and a key are provided below the following table.
1214

1315
toc::[]
@@ -128,7 +130,7 @@ WARNING: If migrator services are down at startup connected services will fail.
128130

129131
| `frontend`
130132
| CircleCI web app and www-api proxy.
131-
| The UI and REST API will be unavailable and no jobs will be triggered by Github/Enterprise. Running builds will be OK but no updates will be seen.
133+
| The UI and REST API will be unavailable and no jobs will be triggered by GitHub/Enterprise. Running builds will be OK but no updates will be seen.
132134
| icon:exclamation-triangle[]
133135
| `postgres`
134136

@@ -182,7 +184,7 @@ WARNING: If migrator services are down at startup connected services will fail.
182184

183185
| `outputRunningRedis` / `redis` *
184186
| The Redis key/value store.
185-
| Lose output from currently-running job steps. API calls out to github may also fail.
187+
| Lose output from currently-running job steps. API calls out to GitHub may also fail.
186188
| icon:exclamation-triangle[]
187189
| None
188190

‎jekyll/_cci2/authentication.adoc

+3-1
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,13 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
This document describes the various ways users of your CircleCI Server installation can get access and authenticate their accounts. Currently OAuth and LDAP are supported as authentication methods.
911

1012
toc::[]
1113

12-
== OAuth with Github/GHE
14+
== OAuth with GitHub/GHE
1315

1416
The default method for user account authentication in CircleCI Server is through GitHub.com/GitHub Enterprise OAuth.
1517

‎jekyll/_cci2/backup.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
This chapter describes failover or replacement of the services machine. Refer to the Backup section below for information about possible backup strategies and procedures for implementing a regular backup image or snapshot of the services machine.
911

1012
toc::[]

‎jekyll/_cci2/build-artifacts.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
Build artifacts persist data after a job is completed. They can be used for longer-term storage of your build process outputs. For example, when a Java build/test process finishes, the output of the process is saved as a `.jar` file. CircleCI can store this file as an artifact, keeping it available long after the process has finished.
911

1012
toc::[]

‎jekyll/_cci2/certificates.adoc

+4-2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
This document provides a script for using a custom Root Certificate Authority and the process for using an Elastic Load Balancing certificate.
911

1012
toc::[]
@@ -129,7 +131,7 @@ NOTE: The sources below are left open so that anybody can access the instance ov
129131

130132
. Next, in the management console for CircleCI, upload a valid certificate and key file to the `Privacy` Section. These don't need to be externally signed or even current certs as the actual cert management is done at the ELB. But, to use HTTPS requests, CircleCI requires a certificate and key in which the "Common Name (FQDN)" matches the hostname configured in the admin console.
131133

132-
. It is now possible to set your Github Authorization Callback to `https` rather than `http`.
134+
. It is now possible to set your GitHub Authorization Callback to `https` rather than `http`.
133135

134136
=== Using Self-Signed Certificates
135137

@@ -190,4 +192,4 @@ More information is available https://letsencrypt.readthedocs.io/en/latest/using
190192

191193
Ensure the hostname is properly configured from the Management Console (`http://<circleci-hostname>.com:8800`) **and** that the hostname used matches the DNS records associated with the TLS certificates.
192194

193-
Make sure the Auth Callback URL in Github/Github Enterprise matches the domain name pointing to the Services machine, including the protocol used, for example `**https**://info-tech.io/`.
195+
Make sure the Auth Callback URL in GitHub/GHE matches the domain name pointing to the Services machine, including the protocol used, for example `**https**://info-tech.io/`.

‎jekyll/_cci2/circleci-images.md

+8
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,14 @@ The following packages are installed via `curl` or other means.
252252
- [dockerize](https://github.com/jwilder/dockerize)
253253
- [jq](https://stedolan.github.io/jq/)
254254
255+
256+
## Out of Scope
257+
258+
1. If an image isn't listed above, it is not available. As the Convenience Image program is revamped, proposals for new images are not currently being accepted.
259+
1. Old versions of software will not be rebuilt. Once an upstream image stops building the tag for a specific release, say Node.js v8.1.0, then we stop building it too. This means other tools in that image, such as `npm` in this example, will no longer be updated either.
260+
1. We don't support building preview, beta, or release candidate images tags. On occasion they'll be available but these tags tend to cause our build system for Convenience Images to fail. If you need a non-stable release of a language, we suggest installing it via [an orb](https://circleci.com/orbs/) or a custom Docker image instead.
261+
262+
255263
## Latest Image Tags by Language
256264
257265
Below is a list of the latest convenience images, sorted by language.

‎jekyll/_cci2/configuration-reference.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -780,7 +780,7 @@ workflows:
780780
781781
##### **`checkout`**
782782
783-
Special step used to check out source code to the configured `path` (defaults to the `working_directory`). The reason this is a special step is because it is more of a helper function designed to make checking out code easy for you. If you require doing git over HTTPS you should not use this step as it configures git to checkout over ssh.
783+
A special step used to check out source code to the configured `path` (defaults to the `working_directory`). The reason this is a special step is because it is more of a helper function designed to make checking out code easy for you. If you require doing git over HTTPS you should not use this step as it configures git to checkout over ssh.
784784
785785
Key | Required | Type | Description
786786
----|-----------|------|------------
@@ -805,6 +805,8 @@ In the case of `checkout`, the step type is just a string with no additional att
805805
- run: git submodule update --init
806806
```
807807
808+
This command will automatically add the required authenticity keys for interacting with GitHub and Bitbucket over SSH, which is detailed further in our [integration guide]({{ site.baseurl }}/2.0/gh-bb-integration/#establishing-the-authenticity-of-an-ssh-host) – this guide will also be helpful if you wish to implement a custom checkout command.
809+
808810
**Note:** The `checkout` step will configure Git to skip automatic garbage collection. If you are caching your `.git` directory with [restore_cache](#restore_cache) and would like to use garbage collection to reduce its size, you may wish to use a [run](#run) step with command `git gc` before doing so.
809811

810812
##### **`setup_remote_docker`**

‎jekyll/_cci2/customizations.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
The following sections summarize the key files and variables that impact CircleCI Server behavior, and configuration options for your Server installation.
911

1012
toc::[]

‎jekyll/_cci2/gh-bb-integration.md

+30
Original file line numberDiff line numberDiff line change
@@ -328,3 +328,33 @@ access to multiple repositories) and user keys have no notion of _scope_
328328
separate from the user associated with them.
329329

330330
To achieve fine-grained access to more than one repo, consider creating what GitHub calls a machine user. Give this user exactly the permissions your build requires, and then associate its user key with your project on CircleCI.
331+
332+
## Establishing the authenticity of an SSH host
333+
334+
When using SSH keys to checkout repositories, it may be neccesary to add the
335+
fingerprints for GitHub or BitBucket to a "known hosts" file
336+
(`~/.ssh/known_hosts`) so that the executor can verify that the host it's
337+
connecting to is authentic. The `checkout`job step does this automatically, so
338+
the following command will need to be used if you opt to use a custom checkout
339+
command.
340+
341+
```
342+
mkdir -p ~/.ssh
343+
344+
echo 'github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
345+
bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw==
346+
' >> ~/.ssh/known_hosts
347+
```
348+
349+
SSH keys for servers can be fetched by running `ssh-keyscan <host>`, then
350+
adding the key that is prefixed with `ssh-rsa` to the `known_hosts` file of your
351+
job. You can see this in action here:
352+
353+
```
354+
➜ ~ ssh-keyscan github.com
355+
# github.com:22 SSH-2.0-babeld-2e9d163d
356+
github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
357+
# github.com:22 SSH-2.0-babeld-2e9d163d
358+
# github.com:22 SSH-2.0-babeld-2e9d163d
359+
➜ ~ ✗
360+
```

‎jekyll/_cci2/gpu.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
This document outlines how to run GPU (graphics processing unit) machine executors using CircleCI Server.
911

1012
toc::[]

‎jekyll/_cci2/hello-world-windows.md

+19
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,25 @@ jobs:
113113
shell: powershell.exe
114114
```
115115

116+
**Note** It is possible to install updated or other Windows shell-tooling as well; for example, you could install the latest version of Powershell Core with the `dotnet` cli and use it in a job's successive steps:
117+
118+
```YAML
119+
120+
version: 2.1
121+
122+
orbs:
123+
win: circleci/windows@1.0.0
124+
125+
jobs:
126+
build:
127+
executor: win/default
128+
steps:
129+
- checkout
130+
- run: dotnet tool install --global PowerShell
131+
- run: pwsh ./<my-script>.ps1
132+
133+
```
134+
116135
# Example Application
117136

118137
Let’s consider a more advanced (but still introductory) "hello world" application using the Windows executor. This [example application](https://github.com/CircleCI-Public/circleci-demo-windows) still prints "Hello World" to the console, but does so using .NET core to create an executable, uses dependency caching, and creates an artifact on every build.

‎jekyll/_cci2/jvm-heap-size-configuration.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
:toc: macro
66
:toc-title:
77

8+
{% include snippets/server-only.adoc %}
9+
810
The JVM heap size is configurable for the following containers: `frontend`, `test-results`, `output-processing` and `contexts-service`. You might want to consider increasing the heap size if you see "out of memory" errors, such as: `Terminating due to java.lang.OutOfMemoryError: Java heap space`.
911

1012
== Setting up

‎jekyll/_cci2/language-java-maven.md

+18
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,24 @@ Next we pull down the cache, if present. If this is your first run, or if you've
117117
project build. If this is the case, consider using the <a href="https://github.com/qaware/go-offline-maven-plugin">go-offline-maven-plugin</a>.
118118
</div>
119119

120+
Multi-module cache should depend on pom.xml in every module, it could be achieved with this additional step:
121+
122+
{% raw %}
123+
```yaml
124+
...
125+
steps:
126+
- checkout
127+
- run:
128+
name: Generate cumulative pom.xml checksum
129+
command: |
130+
find . -type f -name "pom.xml" -exec sh -c "sha256sum {} >> ~/pom-checksum.tmp" \;
131+
sort -o ~/pom-checksum ~/pom-checksum.tmp
132+
when: always
133+
- restore_cache:
134+
key: circleci-demo-java-spring-{{ checksum "~/pom-checksum" }}
135+
```
136+
{% endraw %}
137+
120138
Then `mvn package` runs the actual tests, and if they succeed, it creates an "uberjar" file containing the application source along with all its dependencies.
121139

122140
Next `store_test_results` uploads the test metadata from the `target/surefire-reports` directory so that it can show up in the CircleCI dashboard.

‎jekyll/_cci2/language-scala.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ The following keys represent actions performed after the multi-line command is e
185185
```
186186

187187
Below is an explanation of the preceding example:
188-
- [`checkout`]({{ site.baseurl }}/2.0/configuration-reference/#checkout): basically git clones the project repo from github into the container
188+
- [`checkout`]({{ site.baseurl }}/2.0/configuration-reference/#checkout): basically git clones the project repo from GitHub into the container
189189
- [`restore_cache`]({{ site.baseurl }}/2.0/configuration-reference/#restore_cache) key: specifies the name of the cache files to restore. The key name is specified in the save_cache key that is found later in the schema. If the key specified is not found then nothing is restored and continues to process.
190190
- [`run`]({{ site.baseurl }}/2.0/configuration-reference/#run) command `cat /dev/null | sbt clean update dist`: executes the sbt compile command that generates the package .zip file.
191191
- [`store_artifacts`]({{ site.baseurl }}/2.0/configuration-reference/#store_artifacts) path: specifies the path to the source file to copy to the ARTIFACT zone in the image.

0 commit comments

Comments
 (0)