diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..9edc855 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +build.sh text eol=lf +build.cake text eol=lf \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ed98562 --- /dev/null +++ b/.gitignore @@ -0,0 +1,184 @@ +## Ignore Visual Studio temporary files, build results, and +## files generated by popular Visual Studio add-ons. + +# User-specific files +*.suo +*.user +*.sln.docstates +.vs +.dotnet +tools/* +project.lock.json + +# Build results +artifacts +[Dd]ebug/ +[Dd]ebugPublic/ +[Rr]elease/ +x64/ +build/ +bld/ +[Bb]in/ +[Oo]bj/ + +# MSTest test Results +[Tt]est[Rr]esult*/ +[Bb]uild[Ll]og.* + +#NUNIT +*.VisualState.xml +TestResult.xml + +# Build Results of an ATL Project +[Dd]ebugPS/ +[Rr]eleasePS/ +dlldata.c + +*_i.c +*_p.c +*_i.h +*.ilk +*.meta +*.obj +*.pch +*.pdb +*.pgc +*.pgd +*.rsp +*.sbr +*.tlb +*.tli +*.tlh +*.tmp +*.tmp_proj +*.log +*.vspscc +*.vssscc +.builds +*.pidb +*.svclog +*.scc + +# Chutzpah Test files +_Chutzpah* + +# Visual C++ cache files +ipch/ +*.aps +*.ncb +*.opensdf +*.sdf +*.cachefile + +# Visual Studio profiler +*.psess +*.vsp +*.vspx + +# TFS 2012 Local Workspace +$tf/ + +# Guidance Automation Toolkit +*.gpState + +# ReSharper is a .NET coding add-in +_ReSharper*/ +*.[Rr]e[Ss]harper +*.DotSettings.user + +# JustCode is a .NET coding addin-in +.JustCode + +# TeamCity is a build add-in +_TeamCity* + +# DotCover is a Code Coverage Tool +*.dotCover + +# NCrunch +*.ncrunch* +_NCrunch_* +.*crunch*.local.xml + +# MightyMoose +*.mm.* +AutoTest.Net/ + +# Web workbench (sass) +.sass-cache/ + +# Installshield output folder +[Ee]xpress/ + +# DocProject is a documentation generator add-in +DocProject/buildhelp/ +DocProject/Help/*.HxT +DocProject/Help/*.HxC +DocProject/Help/*.hhc +DocProject/Help/*.hhk +DocProject/Help/*.hhp +DocProject/Help/Html2 +DocProject/Help/html + +# Click-Once directory +publish/ + +# Publish Web Output +*.[Pp]ublish.xml +*.azurePubxml + +# NuGet Packages Directory +packages/ +## TODO: If the tool you use requires repositories.config uncomment the next line +#!packages/repositories.config + +# Enable "build/" folder in the NuGet Packages folder since NuGet packages use it for MSBuild targets +# This line needs to be after the ignore of the build folder (and the packages folder if the line above has been uncommented) +!packages/build/ + +# Bower +bower_components/ + +# Windows Azure Build Output +csx/ +*.build.csdef + +# Windows Store app package directory +AppPackages/ + +# Others +sql/ +*.Cache +ClientBin/ +[Ss]tyle[Cc]op.* +~$* +*~ +*.dbmdl +*.dbproj.schemaview +*.pfx +*.publishsettings +node_modules/ + +# RIA/Silverlight projects +Generated_Code/ + +# Backup & report files from converting an old project file to a newer +# Visual Studio version. Backup files are not needed, because we have git ;-) +_UpgradeReport_Files/ +Backup*/ +UpgradeLog*.XML +UpgradeLog*.htm + +# SQL Server files +*.mdf +*.ldf + +# Business Intelligence projects +*.rdl.data +*.bim.layout +*.bim_*.settings + +# Microsoft Fakes +FakesAssemblies/ +/src/App/stats.json +*.db diff --git a/README.md b/README.md new file mode 100644 index 0000000..81d938a --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# ![Icon](doc/logo.png) PokerTime + +Remote planning poker tool built in ASP.NET Core and Blazor + +Licensed: GNU GPL v3.0 + +[![Build status](https://ci.appveyor.com/api/projects/status/7bjrmgtek7j080d7?svg=true)](https://ci.appveyor.com/project/Sebazzz/PokerTime) +[![CircleCI](https://circleci.com/gh/Sebazzz/PokerTime.svg?style=svg)](https://circleci.com/gh/Sebazzz/PokerTime) +[![Github CI](https://github.com/sebazzz/PokerTime/workflows/Continuous%20integration/badge.svg)](https://github.com/Sebazzz/PokerTime/actions?workflow=Continuous+integration) + +## Features + +- Realtime retrospective app, ideal for remote teams +- Shortcut support: + - Ctrl + lane number for adding notes or groups + - Ctrl + delete for deleting focused note +- Create password protected retrospectives +- As facilitator, lead the retrospective through the writing, grouping and voting phase. +- Overview with highest voted items + +### Browser Support + +Developed and tested on: + +- Internet Explorer 11 +- Microsoft Edge +- Google Chrome +- Mozilla Firefox + +## Download + +Download the release for your OS from the [releases tab](https://github.com/Sebazzz/PokerTime/releases) or download the cutting edge builds from [AppVeyor](https://ci.appveyor.com/project/Sebazzz/PokerTime). + +[Follow the installation instructions](docs/Installation.md) in the documentation to install it. + +## Building PokerTime from sources + +If you prefer to build the application yourself, please follow the [compilation instructions](doc/Building-from-sources.md) in the documentation. + +## Screenshots + +*to-do* + +## Contributions + +Contributions are allowed and encouraged. In general the rules are: same code style (simply use the included `.editorconfig`), and write automated tests for the changes. + +Please submit an issue to communicate in advance to prevent disappointments. + +## Attribution + +Application icon: + +- Icon made by [Eucalyp](https://www.flaticon.com/authors/eucalyp) from [www.flaticon.com](http://www.flaticon.com/) + +Built on: + +- [Bulma](https://bulma.io) _CSS framework_; +- [Fontawesome](http://fontawesome.io/) as _icon framework_; +- [ASP.NET Core 3.1](https://dot.net) (Blazor Server) with [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core/) for _server side logic and data persistence_; diff --git a/doc/Building-from-sources.md b/doc/Building-from-sources.md new file mode 100644 index 0000000..25a1729 --- /dev/null +++ b/doc/Building-from-sources.md @@ -0,0 +1,73 @@ +# Building PokerTime from sources + +If you like to build PokerTime from sources, you can follow the instructions below. + +## Prequisites + +- [.NET Core 3.1 SDK](https://www.microsoft.com/net/download/core). +- [Node.js LTS](https://nodejs.org/en/download/) or higher (Node.js 10.x is supported too). +- [Yarn](https://yarnpkg.com/en/docs/install) or higher + +### Additional prequisites on Windows + +- Windows Powershell or Powershell 7 + +### Additional prequisites on Linux (Ubuntu) + +Environment: + +- Ensure `yarn` and `node` are in your `PATH`. +- Ensure `dotnet` is in your `PATH`. + +For running the build script: + +- Ensure the Powershell execution policy is set to [**RemoteSigned**](https://technet.microsoft.com/en-us/library/ee176961.aspx). + +## Check-out + +Pull the sources from this repository's [home page](https://github.com/Sebazzz/PokerTime). + +## Building + +Use the build script in the root to build the application: + + build + +To create a deployment to one of the supported platforms: + + build -Target Publish + +The results will be emitted in the `build/publish` folder. For additional supported command line parameters run: + + build -h + +## Development + +After you've build the application once you can start developing. + +To develop, just run the application using `dotnet run`. + +If you have not created a database yet, please run `build -Target Generate-MigrationScript` to generate a migration script and run it on a local database. The application will also attempt to seed the database with some base data. + +## Code style and linting + +Code style and linting of TS/JS/JSON is enforced via TSLint and Prettier. If you have run `yarn`, prettier will be run as a pre-commit hook. + +### Editors + +Both Visual Studio and Visual Studio Code work well with the project. + +Recommended extensions for Visual Studio: + +- ReSharper +- TSLint +- [Prettier](https://github.com/madskristensen/JavaScriptPrettier) + +Recommende extensions for Visual Studio Code: + +- Editor support + - csharp +- Code formatting and linting + - tslint + - vscode-prettier + - vscode-status-bar-format-toggle diff --git a/doc/Installation.md b/doc/Installation.md new file mode 100644 index 0000000..52cba7c --- /dev/null +++ b/doc/Installation.md @@ -0,0 +1,189 @@ +# PokerTime installation guide + +This guide will help you in installation of the application. The application is a ASP.NET Core web application and will in the basis 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](https://docs.microsoft.com/nl-nl/aspnet/core/hosting/windows-service), [hosting in Windows IIS](https://docs.microsoft.com/nl-nl/aspnet/core/publishing/iis?tabs=aspnetcore2x) or [hosting on Linux](https://docs.microsoft.com/nl-nl/aspnet/core/publishing/linuxproduction?tabs=aspnetcore2x) pages on the official Microsoft docs for more information. + +## Getting a release + +Download a release from the [releases](https://github.com/Sebazzz/PokerTime/releases) tab. You may also [build the application from sources](Building-from-sources.md) if you like or get a build from AppVeyor. + +## Prequisites + +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 + +For Ubuntu 17.x: + + sudo apt-get install libicu57 + +For Ubuntu 18.x: + + sudo apt-get install libicu57 + +For QR code support in two-factor-authentication: + + sudo apt-get install libgdiplus + cd /usr/lib + sudo ln -s libgdiplus.so gdiplus.dll + +## Installation + +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 + +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`. + +### File-based configuration + +Configuration files are searched on platform-specific paths: + +- Windows + - Common application data (usually `C:\ProgramData\return-retro\config.`) +- Unix / Linux - excluding MacOS + - `/etc/return-retro/config.` + +You can use either `.json` or `.ini` files to configure the application. Using both is not recommended. + +#### INI files + +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 + +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" + } + } + } + +### General configuration - `Server` + +`BaseUrl`: Base URL used for mailing. If not set, auto-detection is attempted. + +### HTTPS configuration - `Server.Https` + +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. + +### Logging configuration - `Logging.File` + +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. + +### Database set-up - `Database` + +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. + +#### Sqlite configuration options + +`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. + +##### Advanced configuration + +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. + +#### SQL Server configuration options + +`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. + +##### Advanced configuration + +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. + +### Application installation + +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 + +### Run + +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. diff --git a/doc/logo.png b/doc/logo.png new file mode 100644 index 0000000..525fad7 Binary files /dev/null and b/doc/logo.png differ