adds troubleshooting and additional info

BlueAcornInc · Aug 9, 2024 · 2e79b9c · 2e79b9c
1 parent af845a1
commit 2e79b9c
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ general-purpose web applications, such as Node.js based PWAs.
 * [Live Demo](https://example-project-ownsyqq-zs5comprbmlgu.us-4.magentosite.cloud/)
 * [Github Repo](https://github.com/BlueAcornInc/adobe-commerce-cloud-hosting-examples-pwa)
 
-## Building and Deploying the App
+## Basic Configuration
 
 Please review the `.magento.app.yaml` file to see the completed solution.
 
@@ -17,13 +17,11 @@ We can optionally install any global node dependancies required to make the solu
 In this example, we're adding the global dependancies needed to build a remix project:
 
 ```yaml
-...
 dependencies:
     nodejs:
         node-sass: "^9.0.0"
         npm-run-all: "4.1.5"
         "@remix-run/dev": "2.11.0"
-...
 ```
 
 ### hooks
@@ -49,6 +47,16 @@ web:
             npm run start:cloud
 ```
 
+### mounts
+
+While this example does not use mounts, one can easily introduce them to allow for read-write operations within the runtime stack. 
+
+```yaml
+mounts:
+    "build": "shared:build/"
+    "public/build": "shared:public-build"
+```
+
 ### Server listening on port 8888 
 
 The base configuration will listen for anything to bind to port 8888 and will try and serve that out to the world. Make sure that your web server is binded to this port. This can be accomplished several ways, but in our example we're using a `npm run` command to set a `PORT` environment variable that is interpreted by our server. 
@@ -99,6 +107,27 @@ npm run start:cloud
 ```
 In this approach, we're _adding_ a npm script which triggers the PORT. This can also be accomplished through setting a Project Variable within Adobe Commerce Cloud, or potentially in the build pipeline itself.
 
+## Troubleshooting
+
+Getting these kinds of applications working can be tricky, especially when in a multi-app arrangement where you're also contenting with a build and deployment of Adobe Commerce Cloud. The following may help you navigate some sticky situations.
+
+### /tmp is read-writable
+
+If you're facing build and dependancy issues that prevent you from getting the application running in the instance, when it works locally, you can often troubleshoot the application by copying the `/app` directory to `/tmp/app` where you can perform steps that require a writable file system. For example:
+
+```bash
+cp /app /tmp/app -rf
+cd /tmp/app
+npm install 
+npm run build
+npm run start
+```
+This will allow you to test build steps in an interactive context where you can experiment a bit.
+
+### Start by Deploying as a Single App
+
+Start by deploying your node project repo seperately as a single-app deployment in a development branch. This will prevent the Adobe Commerce project from performing unnessisary deployments which take forever, could get stuck, and may require a support ticket to deal with. 
+
 ## License
 
 The MIT License is a permissive open-source license that allows for the free use, modification, and distribution of software. It grants permission to anyone, including Adobe and other users of Adobe Commerce Cloud, to freely reuse and host applications on the platform. This license ensures that there are minimal restrictions on the usage of the code, promoting collaboration and innovation. To learn more about the MIT License, you can visit [here](https://opensource.org/licenses/MIT).

diff --git a/server.css b/server.css
@@ -1,14 +1,9 @@
-/* Reset default styles */
-
-
-/* Set sans-serif font family */
 body {
     font-family: Arial, sans-serif;
     margin: 20px auto;
     width: 800px;
 }
 
-/* Add modern flourishes */
 .container {
     display: flex;
     justify-content: center;

diff --git a/server.js b/server.js
@@ -5,7 +5,6 @@ const app = express();
 
 const port = process.env.PORT || 3000; // Use the PORT environment variable or default to 3000
 
-// Function to generate HTML response
 const generateHtmlResponse = (cssData, rawMarkup) => `
   <html>
     <head>
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,6 @@ const app = express(); @@
     const port = process.env.PORT || 3000; // Use the PORT environment variable or default to 3000
-    // Function to generate HTML response
     const generateHtmlResponse = (cssData, rawMarkup) => `
       <html>
         <head>
@@ Expand Down @@