- In order to deploy KotLink server, one needs to have an instance of PostgreSQL already running in their network. This can be achieved by installing Postgres on one of your servers directly, or by using the official docker image, or by provisioning an instance of Postgres from your cloud provider (e.g. Postgres on RDS).
- The second requirement is G Suite or if one's team is really small they can let everybody use their personal gmail accounts to authenticate.
All of the settings that will be mentioned below (e.g. SPRING_DATASOURCE_URL
)
should be provided to KotLink app as environment variables.
For example with Docker this can be achieved with running the container with multiple -e
flags.
SPRING_DATASOURCE_URL
- JDBC connection URL, e.g.jdbc:postgresql://localhost:5432/kotlink
SPRING_DATASOURCE_USERNAME
- username that is used to access Postgres, e.g.kotlinkuser
SPRING_DATASOURCE_PASSWORD
- password that is used to access Postgres, e.g.kotlinkpass
- Go to Credentials in your Google API Console
- Click on Create credentials button, choose OAuth client ID, and then select Web application.
- On the next page, enter any name you see fit, and add the following URL
http://${YOUR_KOTLINK_SERVER_ADDRESS}/login
under Authorized redirect URLs, where${YOUR_KOTLINK_SERVER_ADDRESS}
should be replaced with the domain name / the external ip address of your KotLink server. E.g. The OAuth2 Client ID for local development hashttp://localhost:8080/login
added to Authorized redirect URLs. - Save the generated client ID and client secret for the next step.
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_GOOGLE_CLIENT_ID
- OAuth2 client ID obtained from Google API Console, e.g.115327279391-cqrf3suvt416skdkr8lqvdntgfa90epg.apps.googleusercontent.com
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_GOOGLE_CLIENT_SECRET
- OAuth2 client secret obtained from Google API Console, e.g.SZDICodbaLAkNXjbFKfOFZCO
KOTLINK_SECURITY_ADMIN_EMAIL
- email of the user who has admin privileges and owns the default namespace,KOTLINK_SECURITY_RESTRICT_EDITS_TO_IP_REGEX
- optional regex that limits IPs from which edits can be performed,KOTLINK_SECURITY_OAUTH_ALLOWED_EMAILS
- an array of user emails that can access the server, e.g.[email protected],[email protected]
; set to empty array by default.KOTLINK_SECURITY_OAUTH_ALLOWED_EMAIL_REGEX
- a Java regular expression of user emails that can access the server, e.g..*
for everybody,^$
for nobody, and.*@gmail\.com$
for everything that ends with gmail.com; set to.*
by default.
Please, note that KOTLINK_SECURITY_OAUTH_ALLOWED_EMAILS
and KOTLINK_SECURITY_OAUTH_ALLOWED_EMAIL_REGEX
checks
are combined using OR, and thus if you want to allow only a set of specific users to access the server,
you should set the regex to ^$
(which matches nothing) and emails array to whatever your users' addresses look like.
Most likely you will be running KotLink behind ELB or some other reverse proxy, and in this case you will want to set the following properties to make sure Tomcat is handing X-Forwarded- headers correctly:
SERVER_USE_FORWARD_HEADERS
- must be set totrue
SERVER_TOMCAT_REMOTE_IP_HEADER
- must be set to the remote IP header used by your proxy/LB, most likelyx-forwarded-for
SERVER_TOMCAT_PROTOCOL_HEADER
- must be set to the protocol header used by your proxy/LB, most likelyx-forwarded-proto
SERVER_TOMCAT_INTERNAL_PROXIES
- may need to be set to a regex matching IPs of your proxy/LB nodes, e.g.10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}
; see RemoveIpValve and Spring Boot Reference Guide for more details.
To enable using Redis as a backing store for cache (by default lives in memory) and for session information (by default is stored in Postgres), which in turn will help to improve performance and availability (e.g. without a stand-alone cache you can only have a single-node deployment of KotLink server, as local caches on each node will quickly become stale and cause issues), you can tweak the following properties:
SPRING_REDIS_URL
- must be set toredis://username:password@your-redis-host:6379
(whereusername:password
pair is optional andusername
is always ignored)SPRING_CACHE_TYPE
- must be set toredis
SPRING_SESSION_STORE_TYPE
- must be set toredis
KotLink server also exposes a few endpoints that help with monitoring its status:
/actuator/health
- (unprotected) reports health of the application/actuator/metrics/
and/actuator/metrics/{metric}
- (both behind Basic Auth) allow checking the list of metric names and their concrete values/actuator/prometheus
- (also behind Basic Auth) allows fetching all metrics values in Prometheus format
To access protected endpoint, KotLink has a special user with name kotlinkactuator
password kotlinkpass
.
This user can't access anything other than /actuator/*
and can be changed to have a different name / password via the following two properties:
SPRING_SECURITY_USER_NAME
- defaults tokotlinkactuator
SPRING_SECURITY_USER_PASSWORD
- defaults tokotlinkpass
Note: Redis should also further be configured due to
spring-session/issues/124.
Make sure to set notify-keyspace-events
to eA
.