From ce14e36c92f350a865c446c8b949e065b9a51a99 Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:20:13 +0000 Subject: [PATCH 01/10] docs moved to repo readme --- README.md | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f22829b --- /dev/null +++ b/README.md @@ -0,0 +1,288 @@ +# 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/)
+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. From e30a17574a4183b10d679ad0cc5b574511c55bd1 Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:24:07 +0000 Subject: [PATCH 02/10] minor formatting changes --- README.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index f22829b..98aea90 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,9 @@ 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. +### (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. +This section will detail how to set up Git SCM for Windows. > **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. @@ -22,17 +21,17 @@ If you host the Git repo on the same machine as the application, you will need t 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. +**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/)
Run the installer. Default settings are acceptable. From b9488400df32e3adc299a508b0e62bcd0750b747 Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:24:40 +0000 Subject: [PATCH 03/10] remove warning about repo hosts --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 98aea90..c1c6863 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,6 @@ It is cross-platform compatible, and can be run on Windows or Linux servers. 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. This section will detail how to set up Git SCM for Windows. -> **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. From 368b3e609edd9009f892a8cfcf39cea9117e393d Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:35:42 +0000 Subject: [PATCH 04/10] remove references to Git being optional --- README.md | 84 ++++++------------------------------------------------- 1 file changed, 8 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index c1c6863..009fbd2 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,7 @@ This site combines links & services from the previous intranet site with portals 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 +## (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. This section will detail how to set up Git SCM for Windows. @@ -32,83 +31,16 @@ Each ‘branch’ in the tree organizes groups of changes to the origin. The lea ### Install Git [Download Git SCM for Windows](https://gitforwindows.org/)
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: +### Requirements: - Git must be installed on the host system. [See Server Setup – Install Git](#install-git) for instructions on installing. -#### Deployment +### 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 @@ -189,16 +121,16 @@ Merging branches can get messy and complicated quickly to new Git users, so it w # 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. - + +## Main page +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 +### 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 +### 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: From 6f44b0965e9495a2d9f6b6bafb01ace726d8c343 Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:43:26 +0000 Subject: [PATCH 05/10] link, formatting, and other changes --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 009fbd2..ee3bcf3 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,10 @@ d. Rewrite URL: `/Index.php` 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` -  + +### Configure The App +In the project directory, you should have changed `.env-prod` to `.env` during install. +This file contains our general configurations. By default, it comes preset for your environment, but double check that everything is how you want it. ### 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.) @@ -109,18 +112,14 @@ When new code is pushed to the remote master, it can be synchronized using a sim ```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 -``` +After this is done, run `Update.bat` in the project directory. + +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. 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. +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](#committing-changes) for advice on persisting these. ## Main page Portal Content on the main page is generated from the `portalLinks.yaml` file in the `%project_dir%/config` folder. @@ -194,7 +193,7 @@ Each question/answer object is keyed by a unique string, such as Question_1, Q2, **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 +## Committing Changes 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. @@ -208,9 +207,10 @@ In the interest of simplicity, this section will describe the process for commit |`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 +## 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. +All changes that have not been committed will be discarded. +If you need to revert something that has already been committed, that will not be covered here as it is beyond scope of this document. \ No newline at end of file From 3e0e76c8dc363db9cc2d39590c80ad5b847dfcba Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:45:20 +0000 Subject: [PATCH 06/10] remove 'understanding git' section --- README.md | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/README.md b/README.md index ee3bcf3..4b3f0cb 100644 --- a/README.md +++ b/README.md @@ -9,25 +9,10 @@ This site combines links & services from the previous intranet site with portals 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 -## (Optional, Recommended) Configuring Git +## 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. This section will detail how to set up Git SCM for Windows. -### 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/)
Run the installer. Default settings are acceptable. From 68f981b51ed0bc55b965473b552b8f2d0736f5e1 Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:52:16 +0000 Subject: [PATCH 07/10] initial commit instructions --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4b3f0cb..618d9d1 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Run the installer. Default settings are acceptable. ## Deployment ### Requirements: - Git must be installed on the host system. [See Server Setup – Install Git](#install-git) for instructions on installing. -### Deployment +### Clone the repo 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: ```bash @@ -192,6 +192,12 @@ In the interest of simplicity, this section will describe the process for commit |`git pull` | Pulls pending changes from upstream. ALWAYS do this before a push| |`git push` | Updates upstream origin with the changes made.| +If this is your first time committing, Git will throw an error. You need to configure a name and email to commit under. +Open a terminal and use the following commands. +```bash +git config --global user.name "Your Name" +git config --global user.email "Your@Email" +``` ## Reverting Changes To restore production to the current upstream branch (undoing any changes made locally) use this command ```git From 7fe036029ad666205033f5f636a01a7a92e53524 Mon Sep 17 00:00:00 2001 From: Audrey Jensen Date: Wed, 9 Aug 2023 19:59:56 +0000 Subject: [PATCH 08/10] fix wrong command in Clone the Repo --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 618d9d1..8ceef4f 100644 --- a/README.md +++ b/README.md @@ -22,11 +22,11 @@ Run the installer. Default settings are acceptable. - Git must be installed on the host system. [See Server Setup – Install Git](#install-git) for instructions on installing. ### Clone the repo 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: +2. Copy the link to this repo. This is the address to the page you're looking at now. +3. Use this following command to clone the repository: ```bash -git clone ssh://[user]@jv[hostname/IP]://[aboslute_path_including_Symfony.git] +git clone [the link you copied in step 2] Symfony ``` -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 From 21a476b1b6530a90610ab607a17b70fa0bf96721 Mon Sep 17 00:00:00 2001 From: Audrey Aaliyah Jensen Date: Thu, 31 Aug 2023 15:35:29 -0500 Subject: [PATCH 09/10] add quick links Link to prominent sections in this readme --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 8ceef4f..2482f51 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +[Install](#Install) +[Configuring IIS](#IIS%20Configuration) +[Updating](#Updating) +[Content Management](#Content%20Management) # 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. From cd284f1aa28a87fba9df7da88534fcf6a2b0f3f0 Mon Sep 17 00:00:00 2001 From: Audrey Aaliyah Jensen Date: Thu, 31 Aug 2023 15:37:17 -0500 Subject: [PATCH 10/10] fix quick links --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2482f51..adb1235 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -[Install](#Install) -[Configuring IIS](#IIS%20Configuration) -[Updating](#Updating) -[Content Management](#Content%20Management) +[Install](#install) +[Configuring IIS](#iis-configuration) +[Updating](#updating) +[Content Management](#content-management) # 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.