This guide will help you in installation of the application. The application is a ASP.NET Core web application and will in essence only require a SQL Server database server to get up and running.
Note: This installation guide covers very basic installation, just enough to get the application up and running. It does not cover installation of the application as a systemd or Windows Service, nor setting it up behind any reverse proxy. Please refer to hosting as a Windows service, hosting in Windows IIS or hosting on Linux pages on the official Microsoft docs for more information.
Note: Return also features experimental SQLite support.
PokerTime is available as a docker image. Simply pull it from the Docker hub, and run it:
docker pull sebazzz/return:latest
docker run -p 80:80 sebazzz/return
For further configuration you may want to mount a directory with the configuration:
docker run -p 80:80 -v /path/to/my/configuration/directory:/etc/return-retro sebazzz/return
Download a release from the releases tab. You may also build the application from sources if you like or get a build from AppVeyor.
To run the application you'Il need:
- A virtual machine or Azure website to deploy it to.
- If using Windows, install on Windows Server 2016 or higher.
- If using Linux, install on Ubuntu 16.x or higher.
- Microsoft SQL Server for the database. The free SQL Server Express also works.
- E-mail (SMTP) server if you want account recovery e-mails etc. to work
On Ubuntu install:
sudo apt-get install libunwind8 liblttng-ust0 libcurl3 libssl1.0.0 libuuid1 libkrb5-3 zlib1g
In addition, for Ubuntu 16.x:
sudo apt-get install libicu55 libgdiplus
For Ubuntu 18.x:
sudo apt-get install libicu57 libgdiplus
You can configure the application via environment variables or configuration files.
Settings are grouped per section, and consist of key-value pairs. In this documentation the section name is shown in the title of each configuration.
Environment variables are more easier to configure, but usually also more insecure. The configurations shown below are environment variables (you can set them in bash by export NAME=VALUE and in Powershell via $ENV:NAME = "VALUE").
Section parts and key-value pairs are concatenated by using two underscores. For instance with section Server.Https and setting CertificatePath becomes: SERVER__HTTPS__CERTIFICATEPATH.
Configuration files are searched on platform-specific paths:
- Windows
- Common application data (usually
C:\ProgramData\return-retro\config.<extension>)
- Common application data (usually
- Unix / Linux - excluding MacOS
/etc/return-retro/config.<extension>
You can use either .json or .ini files to configure the application. Using both is not recommended.
INI files groups key-value pairs of the sections with a [section:subsection] header. Key-value pairs are simply key=value. It is probably the most human-editable file format.
For instance with section Server.Https and setting CertificatePath becomes:
[Server:Https]
CertificatePath=path
JSON files follow a standard JSON file format. Each section is an nested object.
For instance with section Server.Https and setting CertificatePath becomes:
{
"Server": {
"Https": {
"CertificatePath": "path"
}
}
}
You can add a appsettings.Production.json file to keep your own settings.
BaseUrl: Base URL used for mailing. If not set, auto-detection is attempted.
To use HTTPs, use the following environment variables:
CertificatePath: Path to pfx file.
CertificatePassword: Password for pfx file.
The server will automatically start on port 80 and 443.
To configure logging to a file:
Path: Path to log file.
FileSizeLimitBytes: Maximum size of log file in bytes. 0 for unlimited.
MaxRollingFiles: Maximum file rollover. 0 for unlimited.
LobbyCreationPassphrase: Passphrase to create a lobby. Prevents anyone without this passphrase from creating retrospectives.
EnableProxyMode: Whether to detect (True) or ignore (False) headers sent by reverse proxies.
Create an new empty database with a case insensitive collation (SQL_Latin1_General_CP1_CI_AS is preferred).
You can set the database settings as follows:
DatabaseProvider: Either SqlServer or Sqlite. Sqlite support is experimental.
Database: Database file path.
In-memory database: For testing purposes you can add the following key/value:
ConnectionString: Mode=Memory;Cache=Shared
This will create an in-memory database.
Set the connection string using:
ConnectionString: Connection string used to connection to the database. Usually: Data Source=file.
Options in the connection string will override manual "simple" configured options above.
Server: Server name and instance.
Database: Database name.
UserID: User ID.
Password: Password.
IntegratedSecurity: Use integrated credentials. Cannot be combined with user id / password.
Encrypt: Database connection encryption enabled.
ConnectionTimeout: Connection timeout to SQL Server. Set to 0 for unlimited. Set to 60 seconds for cloud environments.
Set the connection string using:
ConnectionString: Connection string used to connection to the database. Usually: Server=myserver;Integrated Security=true;Database=mydatabase;MultipleActiveResultSets=true.
Options in the connection string will override manual "simple" configured options above.
Unpack the application on any location, for instance /opt/return-retro.
Modify the connection string in launch.conf.
You can try out the application using:
./launch run
Install the application as a systemd service using:
./launch install
View other options:
./launch --help
To run the application after installation, simply run:
./launch start
The application will launch at the URL specified in launch.conf.
The application will automatically create the database if allowed by its permissions.