Project Setup

Assumptions

The following steps assume you:

• YOU HAVE READ THE WIKI!
• Have already cloned the repository
• Are using Postgres as your Database
• Are using docker as your database environment
• Have a general understanding of servers and software development
• Have an understanding of how to use your personal dev machine (windows, mac, linux)
• Your repository is on the master branch

Windows

System Requirements

On windows you will need to make sure your system supports virtualization. This can be a setting in the bios and or a setting in the Turn Windows Features On or Off setting of the control panel and enabling ALL Hyper-V settings. Another thing to consider is what Edition of windows you are running, if you are not running Windows 10 Pro you may run into issues with docker and virtualization.

You must also install the microsoft development tools on your system, if you have visual studio installed you should have most of these. If you do not the best place to find the cli tools is by looking in the microsoft tools documentation.

The following commands will install the required development tools for:

• Entity Framework Core: dotnet tool install dotnet-ef --global

In the case that you do not have Windows 10 Pro you have several options:

1. Purchase Windows 10 Pro (I personally would recommend this if you are planning on actively developing in the future using a personal machine, you can transfer licenses between machines but it can be a hassle sometimes)
2. Setup Virtual Box on your system (instead of Hyper-V) and run a linux or database instance in the virtual machine
3. Setup a remote server (sql instance, NOT a vm) on a service such as one of the following (this would cost some money, more than likely (generally cheap, sub $10/month))

• Amazon Web Services (AWS)
• Microsoft Azure (Azure)
• Other ie. Kimsufi self hosted

Of the above options number 1 is the easiest and fastest to get setup, unless you are experienced with linux servers or servers in general this is the route I would recommend.

Setup

Navigate to your repository root directory and locate the .env.default file. Duplicate this file in the repository root directory with the name .env. The .env file should NEVER be checked into git as it could contain application secrets (passwords for production, api keys, etc...). The .env.default file should be checked into git and should NEVER contain application secrets. Edit the .env file and fill out the variables to meet what information you want your postgres database to use.

Open your repository root directory in powershell and run the docker command: docker-compose up. This command will pull all repository data from Dockerhub and build the related containers, then launch the containers. After the containers are built you should have a postgres database that has the localhost port exposed that is in the docker-compose.yml file under the section:

services:
  ports:
    - internalPort:exposedPort

We must now configure your appsettings.Development.json file in your project directory. Under the connection strings object make sure to add your database name variable, used by environment variables in c#/.net. Configure your connection string, example:

{
  "ConnectionString": {
    "TimeTrackerDB": "User ID=postgres;Password=example;Host=localhost;Port=5432;Database=StudentTimeTrackerDB;"
  }
}

Make sure your User ID, Password, Host, etc. all corispond with the information entered in your .env file as well as where your container is located. If you are using docker like this setup guide assumes then your host should be localhost.

You will now need to run migrations on your project to bring your database up to the current schema. We do this using Entity Framework Core Code First Migrations. In the project directory enter the following command: dotnet ef database update this will bring the database located at the above connection string up-to-date with the migrations you have.

You should now be able to launch the application.

User Accounts to Login

Three default accounts should be made with the dotnet ef database update command. Should you need to find specifics on the user accounts, see the EF Core seed extension methods.

• Admin User
  • Username: admin
  • Password: Password!
• Instructor User
  • Username: instructor
  • Password: Password!
• Standard User
  • Username: user
  • Password: Password!

Issues with Setup

If you run into any issues with the project setup make sure you understand how the system is working together. If you need to read up on one of the particular topics do so, we have done our best to provide as much documentation as we can about the particular tools that we used within the project. But, we can only document so much before we are basically reading verbatim from the docs of a given tool.

If you run into setup issues they are likely due to one of the following:

• The docker containers are not running
• The database migrations have not been ran
• You are attempting to use a user that does not yet exist (especially if you previously had the project working)
• Your database connection strings are not configured for your specific environment, see the following files
  • appsettings.development.json (development settings will override prod settings when in dev mode)
  • appsettings.json (production settings)
    • Be careful as these files can change due to commits from other developers. These files should NOT be .gitignored as they are used by the .NET runtime environment of our project a possible solution to this issue is to create ignored scripts that are used by the dev environment and alter some of the runtime settings, then ignore these files after changing the runtime and creating default files that will be checked in to the version control repository.

If you are still having problems after doing the above try to run the following commands from the following locations.

• Run 'docker-compose up' from the TimeTracker folder in terminal or command prompt. You should see something like this after the command has successfully ran "database system is ready to accept connections".
• Run 'dotnet ef database update' from TimeCats.web folder in terminal or command prompt. What you should see after running is "Build Successful"
• Order matters, run the commands in the order listed.
• After running those two commands you are ready to double click on the TimeTracker.sln file and run the project in ISS Express.