Deployment: Difference between revisions

From Poetry MP Wiki
Jump to navigation Jump to search
Admin>Soulmate
No edit summary
mNo edit summary
 
(37 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<span id="device-requirements"></span>
This page is for IT administers, Web masters and computer literates who have basic skills of deploying a Website or unzip a file of a software application. The files needed are available in the '''[[Download]]''' area.
= Device Requirements =


<span id="ios"></span>
The backend and the fontend should be hosted in the same host. And the DB engine is with Sqlite.
== iOS ==
 
iPhone X and iOS 14 or above.
 
iPad 5 and iOS 14 or above.
 
<span id="android"></span>
== Android ==
 
Andoid 7
 
<span id="windows-pc"></span>
== Windows PC ==
 
Windows 7, latest Chrome.
 
<span id="mac"></span>
== Mac ==
 
Catalian, Safari 13.1, Chrome 104
 
Yosemite, Chrome 87
 
<span id="production-build"></span>
= Production Build =
 
<span id="front-end"></span>
== Front End ==
 
After running “buildProd.bat”, do the following: 1. Move “ngsw-worker.js” and “ngsw.json” from folder scripts to root. 2. In “ngsw.json”, replace all urls to js file with <code>/scripts/</code> prefix; and make <code>&quot;index&quot;: &quot;/../index.html&quot;</code>.
 
<span id="static-readonly"></span>
= Static Readonly =
 
PoemApp can be a static read only Website, without a Web service backend. The SPA frontend codes may load static JSON data from the Web server, through being configured as StaticReadonly. The poems data is exported into JSON files using the full app. Such deployment makes a static content Website with rich user interfaces and user interactions, including search functions. This is fairly similar to CHM data format and the CHM browser. The initial site title is “Poetry Collection” as defined in the title tag of index.html. And the site title is defined in siteconfig.js as “siteName”.
 
<span id="deploy-to-isp-provided-website"></span>
== Deploy to ISP Provided Website ==
 
An ISP often by default provides a customer with the such Website or Home Pages Service: * <code>http://YourUserName.superisp.com</code>, you have a Website. * <code>http://users.isp.com/YourUserName</code>, you have Home Pages Service, under a Website <code>http://users.isp.com</code> shared by all users/customers.
 
Generally you may use FTP to upload your static contents to there. For more details of uploading, please refer to the instructions provided by your ISP.
 
<span id="isp-gives-you-a-website"></span>
=== ISP gives you a Website ===
 
Good luck. Your SPA should be working right away at <code>http://YourUserName.superisp.com</code>.
 
If your SPA shouldn’t be your home page content, you may want the access URL to your SPA to be such: <code>http://YourUserName.superisp.com/MySPA</code>. For example, you would substitute MySPA with <code>poems</code>.
 
# Create folder MySPA under the Web root.
# Modify the base tag of index.html to <code>&lt;base href=&quot;/MySPA/&quot;&gt;</code>
# Upload the SPA static contents.
 
Through such method, you may host multiple Single Page Applications.
 
<span id="isp-give-you-a-path-to-a-website-shared-by-all-users"></span>
=== ISP give you a path to a Website shared by all users ===
 
To host your SPA at <code>http://users.isp.com/YourUserName</code>, modify the base tag of index.html to <code>&lt;base href=&quot;/YourUserName/&quot;&gt;</code>.
 
To host your SPA at <code>http://users.isp.com/YourUserName/MySPA</code>, modify the base tag of index.html to <code>&lt;base href=&quot;/YourUserName/MySPA/&quot;&gt;</code>.
 
<span id="prepare-poetry-contents"></span>
=== Prepare Poetry Contents ===
 
<span id="customize-website-for-the-sake-of-pwa"></span>
=== Customize Website for the Sake of PWA ===
 
If you don’t expect your users to install the Web app as a mobile app, you don’t have to deal with such customization.
 
<span id="pwa"></span>
==== PWA ====
 
Both the static readonly and the full app are designed with [https://web.dev/progressive-web-apps/ PWA] in mind. You may modify the Web app manifest “manifest.webmanifest” according to the instruction at https://web.dev/add-manifest/. And generally you just need to modify: * Name * Short_Name * Description
 
The default values is for the full app, therefore, it is almost certain you should change them.
 
<span id="seo"></span>
==== SEO ====
 
In Index.html, There is a script section like:
 
<syntaxhighlight lang="html"><script type="application/ld+json">
    {
    "@context": "http://schema.org",
    "@type": "WebApplication",
    "description": "Poetry collection",
    "keywords": "Poetry,Poems,Poet,Muse",
    "browserRequirements": "requires HTML5 support",
    }
</script></syntaxhighlight>
Web spiders will pick up this and make appropriate indexing.
 
<span id="deploy-to-github-pages"></span>
== Deploy to Github Pages ==
 
GitHub gives you are Website like <code>https://YourUserName.github.io</code>. Each repository may have a home page like <code>https://YourUserName.github.io/repo1</code> and <code>https://YourUserName.github.io/repo2</code> and so on. For more details of uploading, please check: <code>https://pages.github.com/</code> or <code>https://docs.github.com/en/pages</code>.
 
The following descriptions assume that you have read the GitHub Pages manual, and the repository gh-pages is already in place.
 
Prerequisites: 1. Production build. Curently I need to change <code>&lt;base href=&quot;/scripts/&quot;&gt;</code> to <code>&lt;base href=&quot;/&quot;&gt;</code>. Such hack is hopefully until NG 15. 1. Copy the build to the gh-pages repository. 1. Modify index.html and ensure <code>&lt;base href=&quot;/poems/&quot;&gt;</code> or alike. For Chinese, optionally do the following: 1. Copy index.html into chinese.html, and ensure <code>&lt;script src=&quot;conf/siteconfig2nd.js&quot;&gt;&lt;/script&gt;</code> 1. Modify conf/siteconfig.js, and set staticReadonly=true, optionally set siteName. For Chinese, optionally do the following: 1. For additional Chinese edition set hasSecondary=true. 2. Optionally set siteName in Chinese. 1. Using the full app, export the published, 1. Rename the JSON files to primary.json and copy to the data folder. For Chinese, optionally do the following: 1. Export the 2nd edition of the published,and copy to <code>data/secondary.json</code>.
 
# Optionally exported image files using the full app, and copy files to folder “api/files/file”.
# Commit and push
# Test
 
<span id="casual-app-fontend-update"></span>
=== Casual App Fontend Update ===
 
# Production build
# Update the following files:
## Clear folder scripts and fill with new files
## index.html and alter base href to “/poems/” or alike.
## optionally updat chinese.html. This can be done through: copy index.html into chinese.html, and ensure <code>&lt;script src=&quot;conf/siteconfig2nd.js&quot;&gt;&lt;/script&gt;</code>
# Commit and push.
 
If there are changes in assets, copy things accordingly.
 
<span id="customize-styles-after-deployment"></span>
=== Customize Styles After Deployment ===
 
<code>font.css</code> is not amongh the NG build process and is referenced in index.html directly. This is an interface for customization of some sections of the app.
 
You can introduce new fonts and new styles to respective sections through altering <code>font.css</code> and copying some font files (WOFF2 typically) under <code>assets/fonts</code>. For more details, check <code>readme.MD</code> in <code>poemsng\src\assets</code>.


There’s a demo site at https://siubuding.github.io/poems/kai/ .
== Deploy to IIS ==


<span id="deploy-to-aws-s3-bucket"></span>
=== '''Prerequisites''' ===
== Deploy to AWS S3 Bucket ==


https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html
# [https://dotnet.microsoft.com/en-us/download/dotnet/7.0 ASP.NET Core Runtime Hosting Bundle] for Windows IIS.
# A Website created with Application Pool of "No Managed Code".


For example: http://fonlow.heroes.s3-website-us-east-1.amazonaws.com/
=== Installation ===


AWS Provide the following means to publish: 1. Web UI the S3 console 2. REST API. This could be used automatic deployment from client sides. 3. AWS SDKs 4. AWS CLI
# Extract the Zip file to the Website root folder.
 
# Alter bin/appsettings.json with `UseHttps: true` to enforce HTTPS.
As part of the AWS Free Tier, you can get started with Amazon S3 for free. Upon sign-up, new AWS customers receive 5GB of Amazon S3 storage in the S3 Standard storage class; 20,000 GET Requests; 2,000 PUT, COPY, POST, or LIST Requests; and 100 GB of Data Transfer Out each month. @ https://aws.amazon.com/s3/pricing/?p=ft&amp;c=wa&amp;z=2
 
And NO HTTPS access.
 
Good enough for Poetry Collection which requires loading basically once.
 
<span id="multiple-poetry-collections-in-one-website"></span>
== Multiple Poetry Collections in One Website ==
 
Each collection has its own index.html and conf and api/files/file, while sharing scripts and assets.
 
An ISP provides a customer with the such Website: <code>http://users.isp.com/UserName</code>
 
Github Pages provides a user with the following Website: <code>https://UserName.github.io/ProjectName</code>
 
To host multiple SPA apps, do the following. 1. Use FTP or GitHub gh-pages to copy each SPA app to a foder, like Heroes 1. Alter index.html’s base ref to <code>/UserName/Heroes/</code> 1. Test <code>http://users.isp.com/UserName/Heroes</code>
 
Even if you have only 1 app, you may still want this way, because in your Web root, you may want other static HTML contents.
 
To host multiple Poetry collections, basically you may do what outlined above. Since these collections should be using the same codebase, it is better to make these collections share the same set of codes, while with separated. 1. In folder <code>/UserName/Collections/</code>, put folders “assets” and “scripts”. 1. Put each collection to <code>UserName/Collections/Collection1</code> and so on. Each collection has its own files and folders: * index.html. Replace the references to scripts to something like <code>&lt;script src=&quot;../scripts/runtime.31b9d232e3f708d6.js&quot;</code>. Everytime the app scripts is updated, changes need to be made accordingly to adapt the new version. * folder conf. Alter sitename and other settings accordingly * folder data * folder api/files/file 1. Test <code>http://users.isp.com/UserName/Collections/Collection1</code>.
 
<span id="data-update"></span>
=== Data Update ===
 
# Using the full app, export the published, and optionally export the 2nd edition of the published.
# Rename the JSON files to primary.json and secondary.json, and overwrite what in the gh-pages repository;
# If there are new image files associated, the copy things to <code>api/files/file/</code>.
# Commit and push.
 
<span id="web-app"></span>
= Web App =
 
During development, the frontend and the backend are often running on different hosts. Almost all features of the app could run well in such config, except the locally hosted pictures. The locally hosted pictures are using related patch in <code>img src</code>, and such constraint is good for static readonly deployment.
 
The backend and the fontend should be hosted in the same host. And the DB engine is with Sqlite.


<span id="build"></span>
'''Remarks:'''
== Build ==


Run “DotNetPublishToLocalIIS.bat” to build and copy files to local IIS hosted site “poems.localhost”.
* It may be beneficial to set a IIS rewrite rule in Web.config to further enforce HTTPS, while this is optional, since the app itself along with ASP.NET Core Runtime Hosting Bundle is capable of redirecting HTTP calls to HTTPS.
* Single Page Applications often have rewrite rules defined either in Web server (IIS or Apache) config for entering the app from any valid frontend routes. Web.config coming with the app supports such. However, when the app is running with Kestrel, web.config is not used.


This site contains directories “Dictionary” and “JiebaResource” which are for Chinese simplifed and traditional convertion.
'''Hints:'''


<span id="release-for-chinese"></span>
If you don't want to purchase a SSL certificate, you may use "[https://letsencrypt.org/ Let's Encrypt]".
=== Release for Chinese ===


Zip the files then the relese is done.
== Windows Desktop App==
The releases for desktop app are basically the same as the ones for Web App, however, the release is hosted in a local Web server Kestrel included in ASP.NET Core Runtime.


<span id="release-for-all-ohters"></span>
=== '''Prerequisites'''===
=== Release for All Ohters ===
#[https://dotnet.microsoft.com/en-us/download/dotnet/7.0 ASP.NET Core Runtime] for Windows


# Remove directories “Dictionary” and “JiebaResource”.
==='''Installation'''===
# In appsettings.json, set <code>SupportChinese</code> to false, or simply remove the setting.
#Extract the Zip file to a desired folder.
#In folder, double click "CreateShortcut.bat" which will create a shortcut on Windows desktop. This shortcut actually runs `StartPoetryApp.ps1` which will launch PoetryApp.exe and open the default Web browser browsing [http://localhost:5000 http://localhost:5300].


Then zip and release.
You can copy or move the shortcut to any launch area of Windows.


<span id="deploy-to-iis"></span>
'''Hints:'''
=== Deploy to IIS ===


Prerequisites: 1. [https://dotnet.microsoft.com/en-us/download/dotnet/6.0 ASP.NET Core Runtime Hosting Bundle]
In case you have other apps running at port 5300, you need to change the following settings:


<span id="desktop-app"></span>
# File `bin/appsettings.json`: Alter Kestrel/Endpoints/Http/Url to "[http://localhost:Port http://localhost:PortNotInUse]", for example, "[http://localhost http://localhost:5310"]
= Desktop App =
#File `StartPoetryApp.ps1`: Alter respective URL of "start-process".
'''Remarks:'''


The releases for desktop app are basically the same as the ones for Web App, however, the release is hosted in a local Web server Kestrel included in ASP.NET Runtime.
*The desktop app's backend is running on Kestrel which does not read web.config with some rewrite rules, and these rules are for entering the app from any valid frontend routes. However, because you almost always enter the frontend the first time through the startup URL, and the service worker of the frontend will then later on take care of the routing. So eventually you later can access the app from any valid frontend routes.
*Likewise, the static read only variant (Poetry Viewer) of the app also rely on the service worker for routing. Poetry Viewer is often hosted in a server without explicit backend and you may not have control of the server config for the rewrite rules.


'''Prerequisites:''' 1. [https://dotnet.microsoft.com/en-us/download/dotnet/6.0 ASP.NET Core Runtime]
==MacOS Desktop App==
[[File:Local app on MacOS.png|thumb|local app on MacOS]]


'''Installation''' 1. Extract the files to a desired folder such as “c:&quot;. 2. In folder, double click”CreateShortcut.bat” which will create a shortcut on Windows desktop
==='''Prerequisites'''===
#[https://dotnet.microsoft.com/en-us/download/dotnet/7.0 ASP.NET Core Runtime] for macOS Binaries Arm64 or x64 and follow [https://learn.microsoft.com/en-us/dotnet/core/install/macos this article]. Optional. If you install the self contained release, you don't need to install the runtime separately.


Double click the shortcut to launch the app.
==='''Installation'''===
# Extract the Zip file to a desired folder, for example, "/Users/YourUsername/Documents/PoetryApp"
#[https://support.apple.com/en-au/guide/terminal/apdd100908f-06b3-4e63-8a87-32e71241bab4/2.12/mac/11.0 Apply "chmod 755" to files "StartPoetryApp.command" and "bin/PoetryApp"] to make both become executable.


You can copy or move the shortcut to any lauch area of Windows.
===Execution===


<span id="mobile-app"></span>
=====In Terminal=====
= Mobile App =
#Under "/Users/YourUsername/Documents/PoetryApp", execute "./StartPoetryApp.command". And this will launch PoetryApp as a local service hosting http://localhost:5300 and open browser Safari or Chrome, and go to http://localhost:5300
[[File:PoetryApp Local Service.png|alt=PoetryApp Local Service|thumb|PoetryApp Local Service]]
=====In Finder=====


<span id="static-readonly-mobile-app"></span>
#Double click "StartPoetryApp.command".
= Static Readonly Mobile App =
'''Hints:'''


This is basically the static readonly self contained in an app container.
You may make an Alias of "StartPoetryApp.command".

Latest revision as of 11:54, 10 November 2022

This page is for IT administers, Web masters and computer literates who have basic skills of deploying a Website or unzip a file of a software application. The files needed are available in the Download area.

The backend and the fontend should be hosted in the same host. And the DB engine is with Sqlite.

Deploy to IIS

Prerequisites

  1. ASP.NET Core Runtime Hosting Bundle for Windows IIS.
  2. A Website created with Application Pool of "No Managed Code".

Installation

  1. Extract the Zip file to the Website root folder.
  2. Alter bin/appsettings.json with `UseHttps: true` to enforce HTTPS.

Remarks:

  • It may be beneficial to set a IIS rewrite rule in Web.config to further enforce HTTPS, while this is optional, since the app itself along with ASP.NET Core Runtime Hosting Bundle is capable of redirecting HTTP calls to HTTPS.
  • Single Page Applications often have rewrite rules defined either in Web server (IIS or Apache) config for entering the app from any valid frontend routes. Web.config coming with the app supports such. However, when the app is running with Kestrel, web.config is not used.

Hints:

If you don't want to purchase a SSL certificate, you may use "Let's Encrypt".

Windows Desktop App

The releases for desktop app are basically the same as the ones for Web App, however, the release is hosted in a local Web server Kestrel included in ASP.NET Core Runtime.

Prerequisites

  1. ASP.NET Core Runtime for Windows

Installation

  1. Extract the Zip file to a desired folder.
  2. In folder, double click "CreateShortcut.bat" which will create a shortcut on Windows desktop. This shortcut actually runs `StartPoetryApp.ps1` which will launch PoetryApp.exe and open the default Web browser browsing http://localhost:5300.

You can copy or move the shortcut to any launch area of Windows.

Hints:

In case you have other apps running at port 5300, you need to change the following settings:

  1. File `bin/appsettings.json`: Alter Kestrel/Endpoints/Http/Url to "http://localhost:PortNotInUse", for example, "http://localhost:5310"
  2. File `StartPoetryApp.ps1`: Alter respective URL of "start-process".

Remarks:

  • The desktop app's backend is running on Kestrel which does not read web.config with some rewrite rules, and these rules are for entering the app from any valid frontend routes. However, because you almost always enter the frontend the first time through the startup URL, and the service worker of the frontend will then later on take care of the routing. So eventually you later can access the app from any valid frontend routes.
  • Likewise, the static read only variant (Poetry Viewer) of the app also rely on the service worker for routing. Poetry Viewer is often hosted in a server without explicit backend and you may not have control of the server config for the rewrite rules.

MacOS Desktop App

local app on MacOS

Prerequisites

  1. ASP.NET Core Runtime for macOS Binaries Arm64 or x64 and follow this article. Optional. If you install the self contained release, you don't need to install the runtime separately.

Installation

  1. Extract the Zip file to a desired folder, for example, "/Users/YourUsername/Documents/PoetryApp"
  2. Apply "chmod 755" to files "StartPoetryApp.command" and "bin/PoetryApp" to make both become executable.

Execution

In Terminal
  1. Under "/Users/YourUsername/Documents/PoetryApp", execute "./StartPoetryApp.command". And this will launch PoetryApp as a local service hosting http://localhost:5300 and open browser Safari or Chrome, and go to http://localhost:5300
PoetryApp Local Service
PoetryApp Local Service
In Finder
  1. Double click "StartPoetryApp.command".

Hints:

You may make an Alias of "StartPoetryApp.command".

Retrieved from "https://poetryappwiki.fonlow.org/w/index.php?title=Deployment&oldid=241"