mirror of
https://github.com/scm-manager/scm-manager.git
synced 2025-10-30 01:55:58 +01:00
236 lines
11 KiB
Markdown
236 lines
11 KiB
Markdown
---
|
|
title: SCM-Server Configuration
|
|
subtitle: Various configuration options for the SCM-Server
|
|
displayToc: true
|
|
---
|
|
|
|
SCM-Manager v3 can be configured in several ways. We recommend using `config.yml` to have most of the settings in
|
|
one place. However, if required, each option in this configuration can also be set via environment variables.
|
|
See the relevant topics below for more information.
|
|
|
|
## Webserver Configuration
|
|
|
|
The listener host and port of your SCM-Server can directly be edited in the top level of your `config.yml`.
|
|
If you want your server without a context path (use `root path`), you can change this option to be `/`.
|
|
|
|
**config.yml**
|
|
|
|
```yaml
|
|
# This is the host adresse, `0.0.0.0` means it listens on every interface
|
|
addressBinding: 0.0.0.0
|
|
# This is the exposed port for your application
|
|
port: 8080
|
|
contextPath: /
|
|
httpHeaderSize: 16384
|
|
```
|
|
|
|
**Environment variables**
|
|
|
|
| Environment Variable | Corresponding config.yml property | Example |
|
|
| -------------------- | --------------------------------- | ---------------------------------- |
|
|
| SCM_ADDRESS_BINDING | addressBinding | export SCM_ADDRESS_BINDING=0.0.0.0 |
|
|
| SCM_PORT | port | export SCM_PORT=8080 |
|
|
| SCM_CONTEXT_PATH | contextPath | export SCM_CONTEXT_PATH=/ |
|
|
| SCM_HTTP_HEADER_SIZE | httpHeaderSize | export SCM_HTTP_HEADER_SIZE=16384 |
|
|
|
|
## SSL
|
|
|
|
In order to use https with SCM-Server, you need a keystore with a certificate and the corresponding secret key.
|
|
In the following we will use openssl to create a self-signed certificate for demonstration purposes.
|
|
|
|
**Warning**: Do not use self-signed certificates in production, this is only for demonstration purposes.
|
|
|
|
```bash
|
|
openssl req -new -x509 -newkey rsa:2048 -sha256 -keyout tls.key -out tls.crt
|
|
```
|
|
|
|
This command will ask a few questions about metadata for generated certificate:
|
|
|
|
- PEM pass phrase: This is a password to protect the scret key
|
|
- Country Name (2 letter code)
|
|
- State or Province Name (full name)
|
|
- Locality Name (eg, city)
|
|
- Organization Name (eg, company)
|
|
- Organizational Unit Name (eg, section)
|
|
- Common Name (eg, fully qualified host name)
|
|
- Email Address
|
|
|
|
Make sure that the common name matches the fqdn, which you are using to access SCM-Manager.
|
|
|
|
### Browsers
|
|
|
|
In order to use a self-signed certificate the certificate must be imported into you browser.
|
|
|
|
### Configure Git
|
|
|
|
To use git with a self-signed certificate, we have to add the certificate path to the configuration.
|
|
|
|
```bash
|
|
git config http.sslCAInfo /complete/path/to/tls.crt
|
|
```
|
|
|
|
### Configure Mercurial
|
|
|
|
To use mercurial with a self-signed certificate, we have to add the certificate path to the configuration.
|
|
|
|
```ini
|
|
[web]
|
|
cacerts = /complete/path/to/cert.pem
|
|
```
|
|
|
|
### Create keystore
|
|
|
|
Create a keystore in pkcs12 format. This command can be used with the self-signed certificate from above or with a valid
|
|
certificate from an authority.
|
|
|
|
```bash
|
|
openssl pkcs12 -inkey tls.key -in tls.crt -export -out keystore.pkcs12
|
|
```
|
|
|
|
If your secret key is protected with a passphrase, you must enter this first. You must then enter an export password to
|
|
protect your keystore.
|
|
|
|
### Server configuration
|
|
|
|
Adjust your `config.yml` to apply your prepared keystore with configured certificate or set them via environment variables.
|
|
|
|
**config.yml**
|
|
|
|
```yaml
|
|
https:
|
|
# If the key store path is not set, the https config will be ignored entirely.
|
|
# This must be set to your created keystore from above.
|
|
keyStorePath: /conf/keystore.pkcs12
|
|
# The password of your keystore.
|
|
keyStorePassword: secret
|
|
# The type of your keystore. Use pkcs12 or jks for java keystore.
|
|
keyStoreType: PKCS12
|
|
# The port of your https connector
|
|
sslPort: 443
|
|
# Automatically redirects incoming http requests to this https connector
|
|
redirectHttpToHttps: true
|
|
```
|
|
|
|
**Environment variables**
|
|
|
|
| Environment Variable | Corresponding config.yml property | Example |
|
|
| -------------------------------- | --------------------------------- | ----------------------------------------------------- |
|
|
| SCM_HTTPS_KEY_STORE_PATH | https.keyStorePath | export SCM_HTTPS_KEY_STORE_PATH=/conf/keystore.pkcs12 |
|
|
| SCM_HTTPS_KEY_STORE_PASSWORD | https.keyStorePassword | export SCM_HTTPS_KEY_STORE_PASSWORD=secret |
|
|
| SCM_HTTPS_KEY_STORE_TYPE | https.keyStoreType | export SCM_HTTPS_KEY_STORE_TYPE=PKCS12 |
|
|
| SCM_HTTPS_SSL_PORT | https.sslPort | export SCM_HTTPS_PORT=443 |
|
|
| SCM_HTTPS_REDIRECT_HTTP_TO_HTTPS | https.redirectHttpToHttps | export SCM_HTTPS_REDIRECT_HTTP_TO_HTTPS=true |
|
|
|
|
## Change directories
|
|
|
|
The default directories are platform-specific and therefore could be different if you try scm-server on different
|
|
operational systems. Paths starting with `/` are absolute to your file system. If you use relative paths without a
|
|
starting `/`, your configured path will be located relative to your base directory of your scm-server (
|
|
like `/opt/scm-server`
|
|
on unix-based packages).
|
|
|
|
For technical reasons the tempDir is located at the top level of your `config.yml`. All other path-based config options
|
|
are located under `webapp`.
|
|
|
|
**config.yml**
|
|
|
|
```yaml
|
|
tempDir: /tmp
|
|
|
|
webapp:
|
|
homeDir: ./scm-home
|
|
workDir: /etc/scm/work
|
|
```
|
|
|
|
**Environment variables**
|
|
|
|
| Environment Variable | Corresponding config.yml property | Example |
|
|
| -------------------- | --------------------------------- | --------------------------------------- |
|
|
| SCM_TEMP_DIR | tempDir | export SCM_TEMP_DIR=/tmp |
|
|
| SCM_WEBAPP_HOMEDIR | webapp.homeDir | export SCM_WEBAPP_HOMEDIR=./scm-home |
|
|
| SCM_WEBAPP_WORKDIR | webapp.workDir | export SCM_WEBAPP_WORKDIR=/etc/scm/work |
|
|
|
|
## Reverse proxy
|
|
|
|
If your SCM-Manager instance is behind a reverse proxy like NGINX, you most likely will have to enable
|
|
X-Forward-Headers.
|
|
These HTTP headers are being appended to the requests which are redirected by your reverse proxy server. Without
|
|
this option set, your SCM-Server may run into connection issues. This option is disabled by default, because without a
|
|
reverse proxy it could cause security issues.
|
|
|
|
Many reverse proxies will also cache response streams. This can lead to timeouts, especially when working with large
|
|
repositories. To avoid this, you might want to increase the `idleTimeout` to a higher value, depending on the size of
|
|
your repositories (you might want to start with `300000`, that would be five minutes).
|
|
|
|
**config.yml**
|
|
|
|
```yaml
|
|
forwardHeadersEnabled: true
|
|
idleTimeout: 300000
|
|
```
|
|
|
|
**Environment variables**
|
|
|
|
| Environment Variable | Corresponding config.yml property | Example |
|
|
| --------------------------- | --------------------------------- | --------------------------------------- |
|
|
| SCM_FORWARD_HEADERS_ENABLED | forwardHeadersEnabled | export SCM_FORWARD_HEADERS_ENABLED=true |
|
|
| SCM_IDLE_TIMEOUT | idleTimeout | export SCM_IDLE_TIMEOUT=300000 |
|
|
|
|
## Webapp
|
|
|
|
The webapp configuration consists of anything that is not webserver or logging related.
|
|
Most of the available options should be set to the recommended values of your default `config.yml` file.
|
|
You can also override these options with environment variables.
|
|
|
|
**config.yml**
|
|
|
|
```yaml
|
|
webapp:
|
|
## Sets explicit working directory for internal processes, empty means default java temp dir
|
|
workDir:
|
|
## Home directory "scm-home" which is also set for classpath
|
|
homeDir: /var/lib/scm
|
|
cache:
|
|
dataFile:
|
|
enabled: true
|
|
store:
|
|
enabled: true
|
|
# name of initial admin user (this is normally set over the ui on the first start)
|
|
initialUser: scmadmin
|
|
# password of initial admin user (this is normally set over the ui on the first start)
|
|
initialPassword: scmadmin
|
|
# if true skip the creation of initial admin user completely
|
|
skipAdminCreation: false
|
|
## Warning: Enabling this option can lead to security issue.
|
|
endlessJwt: false
|
|
## Number of async threads
|
|
asyncThreads: 4
|
|
## Max seconds to abort async execution
|
|
maxAsyncAbortSeconds: 60
|
|
## Amount of central work queue workers
|
|
centralWorkQueue:
|
|
workers: 4
|
|
## Strategy for the working copy pool implementation [sonia.scm.repository.work.NoneCachingWorkingCopyPool, sonia.scm.repository.work.SimpleCachingWorkingCopyPool]
|
|
workingCopyPoolStrategy: sonia.scm.repository.work.SimpleCachingWorkingCopyPool
|
|
## Amount of "cached" working copies
|
|
workingCopyPoolSize: 5
|
|
```
|
|
|
|
**Environment variables**
|
|
|
|
| Environment Variable | Corresponding config.yml property | Example |
|
|
| ----------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
| SCM_WEBAPP_WORKDIR | webapp.workDir | export SCM_WEBAPP_WORKDIR=/tmp/scm-work |
|
|
| SCM_WEBAPP_HOMEDIR | webapp.homeDir | export SCM_WEBAPP_HOMEDIR=/var/lib/scm |
|
|
| SCM_WEBAPP_CACHE_DATAFILE_ENABLED | webapp.cache.datafile.enabled | export SCM_WEBAPP_CACHE_DATAFILE_ENABLED=true |
|
|
| SCM_WEBAPP_CACHE_STORE_ENABLED | webapp.cache.store.enabled | export SCM_WEBAPP_CACHE_STORE_ENABLED=true |
|
|
| SCM_WEBAPP_ENDLESSJWT | webapp.endlessJwt | export SCM_WEBAPP_ENDLESSJWT=false |
|
|
| SCM_WEBAPP_ASYNCTHREADS | webapp.asyncThreads | export SCM_WEBAPP_ASYNCTHREADS=4 |
|
|
| SCM_WEBAPP_MAXASYNCABORTSECONDS | webapp.maxAsyncAbortSeconds | export SCM_WEBAPP_MAXASYNCABORTSECONDS=60 |
|
|
| SCM_WEBAPP_CENTRALWORKQUEUE_WORKERS | webapp.centralWorkQueue.workers | export SCM_WEBAPP_CENTRALWORKQUEUE_WORKERS=4 |
|
|
| SCM_WEBAPP_WORKINGCOPYPOOLSTRATEGY | webapp.workingCopyPoolStrategy | export SCM_WEBAPP_WORKINGCOPYPOOLSTRATEGY=sonia.scm.repository.work.SimpleCachingWorkingCopyPool |
|
|
| SCM_WEBAPP_WORKINGCOPYPOOLSIZE | webapp.workingCopyPoolSize | export SCM_WEBAPP_WORKINGCOPYPOOLSIZE=5 |
|
|
| SCM_WEBAPP_INITIALUSER | webapp.initialUser | export SCM_WEBAPP_INITIALUSER=scmadmin |
|
|
| SCM_WEBAPP_INITIALPASSWORD | webapp.initialPassword | export SCM_WEBAPP_INITIALPASSWORD=scmadmin |
|
|
| SCM_WEBAPP_SKIPADMINCREATION | webapp.skipAdminCreation | export SCM_WEBAPP_SKIPADMINCREATION=true |
|