intranet/README.md

# Overview
An overhaul of J.V. Manufacturing's corporate Intranet page.  
This site combines links & services from the previous intranet site with portals to access ticket repositories from old SpiceWorks On-prem helpdesks. 
## Features
* Quick access links for useful sites & documents
* Portals accessing historical tickets from Request & Sales helpdesks
* PHP rewrite of the J.V. Safety Quiz
## Platform
Based on Symfony 6.3.3, a php framework for developing web applications.  
It is cross-platform compatible, and can be run on Windows or Linux servers.
# Install
## Server Setup
(Optional, Recommended) Configuring Git
The recommended way to manage the app is through version-control software, such as Git. Git is recommended as it greatly simplifies continuous integration/development and provides a robust system for managing application versions.
In absence of a dedicated Git server (such as Gitlab or Github) a local install may be used. This is not ideal, however it probably is not worth running a dedicated system to serve git repositories unless we are maintaining multiple codebases.
This section will detail how to set up Git SCM for Windows using OpenSSH for communication.

> **WARNING!**
If you host the Git repo on the same machine as the application, you will need to make sure you’re keeping backups somewhere safe. If you don’t do this and data on the server is lost, the only other copies will be on development machines. 

### Understanding Git
Imagine our repository as a tree. The trunk is our ‘origin’, or master upstream branch, from which everything branches off. 
Each ‘branch’ in the tree organizes groups of changes to the origin. The leaves on these branches represent individual changes to files. A leaf may be a change to a specific line, or a whole new file.
#### Definitions
Git: Version-control software used frequently to track history & manage changes to files. Most commonly used in software development.
Working Tree: A tree-graph of changes made to tracked files.
Tracked files: any file that is being monitored by Git.
Branch: Collections of changes. Branches may have branches of their own, which can each contain differing versions of the same file.
Merge: The process of merging changes from one branch to another.
Remote: A repository other than the local that changes are synced to. A local repo may have multiple remotes.
Upstream: Typically refers to an item on the remote that the local copy is based on.
Downstream: Refers to items that are based on this. The production & development clones are all downstream from the Remote.
Commit: The process where changes are applied to a repository.
Push: Commits are copied (pushed) TO the upstream branch.
Pull: Commits are copied (pulled) FROM the upstream branch and applied to files in the repository.
### Install Git
[Download Git SCM for Windows](https://gitforwindows.org/)<br>
Run the installer. Default settings are acceptable.
### Install OpenSSH Server
SSH will be used by Git for communications, as the git:// protocol does not support authentication and we are not using a webserver for http. 
1.	On Windows 11, open Settings -> Apps -> Optional Features 
2.	Select ‘View features’ at the top of the window
3.	Locate and install “OpenSSH Server”
Once this is finished, we’ll need to manually start the OpenSSH service.
1.	Open the Windows Services manager using your favorite method.
2.	Locate ‘OpenSSH SSH Server’ and manually start it.
a.	If you want to use keypair authentication, also start ‘OpenSSH Authentication Agent’
3.	Right-click each service you need and enter Properties. Set Startup type to Automatic (Delayed)
4.	Click Apply and close both windows.
Finally, we’ll need to test our connection.
1.	On another machine, open a terminal and use the following command
`ssh [user]@jv@[hostname/IP]`

2.	When prompted about a fingerprint, type ‘Yes’
3.	Enter your password. Character entry will not be echoed. Hit ‘Enter/Return’ 
If the SSH server is running correctly, you should now in a terminal connected to the remote host.

### Configure OpenSSH Server
By default, OpenSSH will connect to a cmd.exe instance. For Git over SSH to work correctly we’ll need to change this to the Bash install provided by Git.
1.	Open a PowerShell terminal to the remote host. You may use an SSH connection for this. If you do, your first command should be `powershell`
2.	Type the following one-line command:
`New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\Windows\Program Files/Git/bin/bash.exe" -PropertyType String -Force`
3.	Close all SSH connections to the server. You may need to restart the OpenSSH Server service on the remote host.
New SSH connections will now use Bash. If you need to access PowerShell in the future, simply use the `powershell` command in Bash.
### Initialize a Bare Repository
A bare repository is a Git repo created without a working tree. Put simply, it’s a repository that’s not intended to be modified by anything other than Git. Any changes to the files within cannot be made here.
A new repository will be created on the server, which will be what we point our app host & development machines to. This should NOT be the same location/repository as the actual app host and should ideally not even be on the same machine.
1.	Open a terminal (bash, cmd, or powershell are all acceptable) in the location you want to keep the repo and run 
`git init --bare Symfony.git`


You should now see a new folder named ‘Symfony.git’ here. The ‘.git’ naming convention is common for bare repositories. Move into the directory and type `git status` to confirm the operation completed successfully.
### Push to Git
The app code is already configured as a Git repository, so there’s no need to initialize a new one. We just need to push this code to our new upstream repository.
1.	On the machine where the code is present (likely the development machine at this point) open a terminal to the working directory (where all the project files are. This will be the same directory containing composer.json)
2.	Use the following command to make sure we’re on master, the main branch.
```bash
git checkout master -force
git restore
```
-	If there are pending unstaged changes, these will be discarded. 
3.	Use the command below to add the new bare repository as a remote with the name ‘Intranet’:
```bash
git remote add Intranet ssh://[user]@jv@[hostname/IP]:/[absolute_path_to_bare_repo]
```

4.	Finally, use this command to push master to  the remote:
```bash
git push --set-upstream Intranet master
```

If everything went well, the bare repo should now contain the application files.  
Git can now be used to track changes to the code and synchronize them between repositories. When ready to update the app with these new changes, all you’ll have to do is pull them and restart the web server.
See the Git sub-section in Deployment to learn how to clone this repository for development or hosting.
## Deployment
### Simple
Deployment can simply be copying all of the website application’s files over to the server.  
There’s no absolute rule on where these files should be placed, so long as they’re in their own directory and the folder structure remains unchanged.
For simplicity, it’s recommended to place this folder on the root of the disk. For example, `C:/Symfony`

### Git (Recommended)
If you’ve set up a Git repository, you can clone directly from that. The advantages of deploying this way is that future changes will be simplified and reverting them will be made easier.
#### Requirements:
-	Git must be installed on the host system. [See Server Setup – Install Git](#install-git) for instructions on installing.
#### Deployment
1.	Open a terminal to the root of the C drive, or wherever the production code will reside.
2.	Use this following command to clone the upstream repository:
a.	Hosted on remote system
```bash
git clone ssh://[user]@jv[hostname/IP]://[aboslute_path_including_Symfony.git]
```
b.	Hosted locally (or on NAS) in another directory:
```bash
Git clone file:///[absolute_path_including_Symfony.git]
```
3.	Enter your password when prompted, and the repository should be cloned into /Symfony
4.	The tickets database is included in the clone, but attachments are not. The default and sales folders will need to be copied into Symfony/public/TicketAttachments manually. Failure to do so will result in broken attachments.
5.	In the project root find the file .env.prod and make a copy of it. Rename the copy to .env 
 - Look through the contents of .env and make sure these settings match your needs. Specifically, look at who will receive complaint emails

### IIS Configuration
https://learn.microsoft.com/en-us/iis/application-frameworks/scenario-build-a-php-website-on-iis/configuring-step-1-install-iis-and-php  
These instructions are based on Microsoft’s official documentation at the link above.
#### Prerequisites:
-	PHP 8.x.x
-	Composer, latest version
-	IIS with CGI
#### Installing PHP
[Download PHP](https://windows.php.net/download/)
You need the NON-THREAD-SAFE VERSION  
1.	Create a new folder in C:/php and extract the contents of the php zip there.
2.	In C:/php locate php.ini – production and rename it to php.ini
3.	Add C:/php to the system PATH variable
4.	Edit php.ini, find `;extension = php_openssl.dll` and remove the semicolon
5.	Repeat step 4 with the lines `extension = php_sqlite.dll` and `extension = php_sqlite3.dll`
6.	Save and close php.ini
#### Install Composer
[Download the Windows installer here](https://getcomposer.org/download/)  
If you haven’t yet added PHP to the PATH var, then do that first. After that’s done, just run the installer and install it for all users.
#### Install URL Rewrite 2 for IIS
[Get URL Rewrite here](https://download.microsoft.com/download/1/2/8/128E2E22-C1B9-44A4-BE2A-5859ED1D4592/rewrite_amd64_en-US.msi)  
Simply run the installer. IIS needs to be installed already. 
#### Configure IIS for PHP
Open IIS Manager. 
1.	Add a new website, name it something like Intranet. Make sure Symfony gets its own Application Pool.
2.	The physical path should route to the `public` folder inside the Symfony directory.
3.	The protocol should be HTTP on port 80. 
4.	Uncheck `Start Website Immediately` and click OK.
5.	In Connections select the new website and then open Handler Mappings
6.	Under Actions click Add Module Mapping  
a.	Request Path should be `*.php`  
b.	Module should be set to FastCgiModule  
c.	Executable should be set to the path to php-cgi.exe that was bundled with your PHP install.  
d.	Name can be FastCGI  
7.	Back in the Connections pane select the new website again. Then open URL Rewrite
8.	In the Actions pane, click Add Rules, under Inbound Rules select Blank rule and name the new rule File Request  
a.	Set the Pattern to `/(.*)`  
b.	Under Conditions, add 3 new rules  
i.	Change ‘Check if input string:’  to Is a File and click OK.  
ii.	Change ‘Check if input string:’ to Does Not Match the Pattern and set the Pattern to ‘.php’ without quotes. Enable Ignore case and click OK.  
iii.	Change ‘Check if input string:’ to Does Not Match the Pattern and set the Pattern to ‘.htm’ without quotes. Enable Ignore case and click OK.  
c.	Under Action, set Action Type to None  
d.	Under Action, enable Stop processing of subsequent rules  
e.	In Actions (on the right) click Apply and then Back to Rules  
9.	Repeat step 8, but configure the new rule as follows  
a.	Name: Symfony Routing  
b.	Pattern: `/(.*)`  
c.	Action: Rewrite  
d.	Rewrite URL: `/Index.php`  
10.	Recycle the Application Pool for the intranet website and test.
11.	(Optional) Prepare the site cache  
a.	Open a terminal into the web app folder (i.e. C:/Symfony)  
b.	Run: `php bin/console cache:warmup`  
 
### Final Deployment Considerations
-	Make sure the IIS user (ISUR or whatever the AppPoolIdentity is) has read & write privileges within the /var directory.
-	Make sure Symfony is not running in DEBUG mode (APP_DEBUG should not be true in env vars.)  

## Updating
When new code is pushed to the remote master, it can be synchronized using a simple command:
```bash
git pull
```
So long as best practices with Git are respected, and the remote is available, the production codebase should be updated to reflect the most recent version.
After this is done, open a terminal to the project root (where bin is located) and run these commands, in this order:
```bash
php bin/console cache:clear
php bin/console cache:pool:prune
php bin/console cache:warmup
```
If you don’t see any changes, then it’s possible that master is behind another branch containing the new code. If this is the case, you’ll need to merge that branch into master before pulling. 
Merging branches can get messy and complicated quickly to new Git users, so it will not be explained here. Best practice dictates no changes should ever be made directly to master so it is highly recommended to learn some Git basics before modifying any code.
# Content Management
Changing page contents is mostly handled within special configuration files. Changes made to these files are reflected immediately upon saving. 
If you’ve chosen to deploy using Git, it’s important to know that changes made to production files may be overwritten during the next pull if they’re not committed. See the section [Committing Changes to Git](##committing-changes-to-git) for advice on persisting these.
Portal
Content on the main page is generated from the `portalLinks.yaml` file in the `%project_dir%/config` folder.
 
The file follows the structure in which the data will be rendered on the webpage. Links are separated into objects (cards on the webpage.) Cards and links render in the order they’re given in the YAML file.
## Creating Cards
Create a new line in `portalLinks.yaml` and indent it with 2 spaces. Type the UNIQUE title of the card and append a colon at the end. Save the file. An empty card will now be rendered when the page is loaded
  
 

## Creating Links
1.	Create a new line under the card you want the link to be contained in.
2.	Indent the new line with 5 spaces. Add a hyphen (dash) followed by another space.
3.	Paste this YAML onto the new line: 
```yaml
{ title: 'Example Link', url: '', disabled: false}
```
4.	Replace the placeholder values accordingly:  
a.	title: The text to be displayed  
b.	url: the path this should link to. If internal, relative is fine. If external, use the absolute URI.  
c.	disabled: Optional. If included and set to true, the button will be rendered but inactive.  
5.	Save the file. The changes should be visible the next time the homepage is loaded by a client.
 
 
 
## Message of the Day (MOTD)
 
The MOTD is a banner that is displayed at the top of every page. It’s great for making announcements to users, such as advising them of an issue or advertising a new feature.  
The message’s contents are read from the ‘MOTD’ environment variable. Changes to this value are visible immediately.  
If this value is blank, the MOTD will not be rendered.
## Safety Training Documents
Just like the main portal page, content on the Safety site as well as quiz questions are generated from YAML files.
### Creating Training Topics
#### Building the Page
Make a new file under `%project_dir%/templates/Training/Safety/Topics`. Name this file `[name].html.twig`. Filenames should be lowercase.
Each html.twig file should have HTML placed between html and body tags, as you would with any other webpage.  

> **Notice:** *Header and navbars are inserted by the controller during rendering. There is no need to manually add these elements.*

#### Serving Files
Any file (such as videos) placed in the web root (`%project_dir%/public`) can be served to users. Symfony will automatically generate links to these files.
1.	Place the file you want to serve in the public folder. Using a subdirectory in this location is encouraged.
2.	In the .html.twig file, determine where you want the link and define a code block by places 2 enclosed curly-brackets. {{ }}
3.	Inside of the brackets, type asset(‘someLinkHere.pdf’) Replace someLinkHere with the relative path to the file to serve from public
##### Example: video.mp4 is at ./public/videos/video.mp4
```twig
{{ asset(‘videos/video.mp4’) }}
```
So long as this file actually exists (and you remembered to save the .html.twig document) this code block will be replaced with a link to the file when the page is loaded.  
If this file exists but a 404 error is returned, then the filename may need to be changed to something IIS can recognize. Remove spaces and unusual characters from the file name. 
 
#### Adding the Link
With the page created, adding a new link is easy.
Navigate to `%project_dir%/config/safetyLinks.yaml` and edit the file in any text editor.
By default, this file is split into 3 sections, keyed by the name of the card. Figure out which card you want the new link on and make a new line under it following the example of the rest of the file.  
You may copy this YAML snippet as a starting point:
```YAML
    - { title: 'Link Title', url: 'somesubject', disabled: false}
```
**title:** This is what will be displayed as the text when a link is rendered  
**url:** This should be the FIRST PART of the filename of the html.twig file. If the full filename is ‘safetyFirst.html.twig’ then this value should be ‘safetyFirst’ case-sensitive.  
**disabled:** False by default. If set to true, the link will be rendered but will be inactionable.
  

## Safety Quiz – Managing Questions
The YAML file for this section is at `%project_dir%/config/SafetyQuiz.yaml`
 
The Safety Quiz supports multiple-choice questions, and allows for multiple correct answers.  There is no requirement for number of questions and options. 
### Object Structure
Each question/answer object is keyed by a unique string, such as Question_1, Q2, etc. This string does not get used by the quiz, so it doesn’t matter what this is.  
**Text:** The question itself. This is what the tester will see.  
**Choices:** Answer options for the question go here.   
	**Label:** The text that’s displayed to represent the selection  
	**Value:** A True/false determining if this is the correct answer or not.  
## Committing Changes to Git
Changes made to production code will have to be discarded before any updates can be pulled from the upstream repository that modify those changed files. In case the production repo has to be restored, these changes will also be lost unless they’re committed and pushed upstream.
In the interest of simplicity, this section will describe the process for committing changes directly to master. This goes against best practice, but will be fine for page config changes.

1.	Open a terminal to the project root. On production, this should be C:/Symfony
2.	Use the following commands to stage * changes, commit them, and push the changes upstream:

|Command	| Description |
| -------- | --------------------------------- |
| `git add [filename]` |	Instructs git to track the file at the specified relative path. Wildcards may be used |
| `git commit -m “[Commit Message]”` |	Commits changes to the current branch (likely master) with the provided message. Message should be a short description of changes. Example: ‘add sharepoint portal link’|
|`git pull` |	Pulls pending changes from upstream. ALWAYS do this before a push|
|`git push` |	Updates upstream origin with the changes made.|

##  Git – Reverting Changes
To restore production to the current upstream branch (undoing any changes made locally) use this command
```git
git restore
```
All changes that have not been committed will be discarded.