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
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.

4. Open the Windows Services manager using your favorite method.

5. Locate ‘OpenSSH SSH Server’ and manually start it. a. If you want to use keypair authentication, also start ‘OpenSSH Authentication Agent’

6. Right-click each service you need and enter Properties. Set Startup type to Automatic (Delayed)

7. Click Apply and close both windows. Finally, we’ll need to test our connection.

8. On another machine, open a terminal and use the following command ssh [user]@jv@[hostname/IP]

9. When prompted about a fingerprint, type ‘Yes’

10. 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.

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’:

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:

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 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

git clone ssh://[user]@jv[hostname/IP]://[aboslute_path_including_Symfony.git]

b. Hosted locally (or on NAS) in another directory:

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 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
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
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:

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:

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 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:

{ 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

{{ 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:

    - { 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 restore

All changes that have not been committed will be discarded.