cloud-node-container/USER-GUIDE.md

User Guide: Deploying Applications with Cloud Node Container

Quick Start (For Non-Node.js Users)

If you've never used Node.js before, don't worry! This container makes it simple.

What You Need to Know

Node.js is like PHP, but for JavaScript. Instead of Apache serving PHP files, your JavaScript code runs as a server application.

Express.js is like a web framework (similar to Laravel for PHP) that makes it easy to handle web requests.

Basic Workflow Comparison

PHP/Apache Workflow	Node.js Container Workflow
Put .php files in web directory	Put .js files in user/app/
Apache serves files directly	Express.js handles requests
Database connection in each file	Server runs continuously
<?php echo "Hello"; ?>	res.send("Hello")

Step-by-Step: Deploy Your First App

1. Create Your Application Files

Create these two files in your user/app/ directory:

File: package.json

{
  "name": "my-first-app",
  "version": "1.0.0",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

File: server.js

const express = require('express');
const app = express();
const port = process.env.PORT || 3000;

// Serve static files (HTML, CSS, images) from 'public' folder
app.use(express.static('public'));

// Route for home page
app.get('/', (req, res) => {
    res.send(`
        <h1>Welcome to My Website!</h1>
        <p>This is running on Node.js</p>
        <a href="/about">About Page</a>
    `);
});

// Route for about page
app.get('/about', (req, res) => {
    res.send(`
        <h1>About Us</h1>
        <p>This website is powered by Node.js and Express</p>
        <a href="/">Back to Home</a>
    `);
});

// Health check (required by container)
app.get('/ping', (req, res) => {
    res.json({ status: 'ok', timestamp: new Date() });
});

// Start the server
app.listen(port, () => {
    console.log(`Server running on port ${port}`);
});

2. Start Your Container

./local-dev.sh -n my-first-app

3. Access Your Site

Visit https://localhost (accept the SSL warning) and you'll see your website!

Common Use Cases

Static Website (Like HTML/CSS sites)

Put your HTML files in user/app/public/ and use this simple server:

const express = require('express');
const app = express();

app.use(express.static('public'));
app.get('/ping', (req, res) => res.json({ status: 'ok' }));

app.listen(3000, () => console.log('Static site running'));

Form Processing (Like PHP forms)

const express = require('express');
const app = express();

app.use(express.urlencoded({ extended: true })); // Process form data
app.use(express.static('public'));

// Show contact form
app.get('/contact', (req, res) => {
    res.send(`
        <form method="POST" action="/contact">
            <input name="name" placeholder="Your Name" required>
            <input name="email" type="email" placeholder="Email" required>
            <textarea name="message" placeholder="Message" required></textarea>
            <button type="submit">Send</button>
        </form>
    `);
});

// Process form submission
app.post('/contact', (req, res) => {
    const { name, email, message } = req.body;
    
    // Here you would save to database, send email, etc.
    console.log('Contact form:', { name, email, message });
    
    res.send(`<h1>Thanks ${name}!</h1><p>We received your message.</p>`);
});

app.get('/ping', (req, res) => res.json({ status: 'ok' }));
app.listen(3000);

Database Connection (Like MySQL in PHP)

const express = require('express');
const app = express();

// In package.json dependencies, add: "mysql2": "^3.6.0"
const mysql = require('mysql2');

const db = mysql.createConnection({
    host: 'localhost',
    user: 'your_user',
    password: 'your_password',
    database: 'your_database'
});

app.get('/users', (req, res) => {
    db.query('SELECT * FROM users', (err, results) => {
        if (err) {
            res.status(500).json({ error: err.message });
        } else {
            res.json(results);
        }
    });
});

app.get('/ping', (req, res) => res.json({ status: 'ok' }));
app.listen(3000);

File Structure Examples

Simple Website

user/app/
├── package.json
├── server.js
└── public/
    ├── index.html
    ├── about.html
    ├── style.css
    └── images/
        └── logo.png

API Application

user/app/
├── package.json
├── server.js
├── routes/
│   ├── users.js
│   └── products.js
└── public/
    └── api-docs.html

Key Differences from PHP

Concept	PHP	Node.js
File serving	Apache serves .php files directly	Express routes handle requests
Variables	$variable	let variable
Arrays	$arr = array()	let arr = []
Echo/Print	echo "Hello"	res.send("Hello")
Include files	include 'file.php'	require('./file.js')
Database	Connect in each file	Connect once, reuse connection
Sessions	$_SESSION	req.session (with middleware)
Forms	$_POST	req.body (with middleware)

Troubleshooting

Common Issues for PHP Users

Issue: "Cannot GET /" error Solution: Make sure you have an app.get('/', ...) route defined

Issue: Static files (CSS/images) not loading
Solution: Put them in public/ folder and add app.use(express.static('public'))

Issue: Forms not working Solution: Add app.use(express.urlencoded({ extended: true })) before your routes

Issue: App crashes on restart Solution: PM2 will automatically restart it, but check logs in user/logs/nodejs/

Getting Help

• Check container logs: ./instance_logs
• Check your app specifically: docker exec -it your-container-name pm2 logs
• Access container shell: ./instance_shell
• Health check: Visit /ping to see if your app is responding

Advanced Features

Using Sessions (like PHP $_SESSION)

// Add to package.json dependencies: "express-session": "^1.17.3"
const session = require('express-session');

app.use(session({
    secret: 'your-secret-key',
    resave: false,
    saveUninitialized: false
}));

app.get('/login', (req, res) => {
    req.session.user = 'john_doe';
    res.send('Logged in!');
});

app.get('/profile', (req, res) => {
    if (req.session.user) {
        res.send(`Hello ${req.session.user}!`);
    } else {
        res.send('Please log in');
    }
});

File Uploads

// Add to package.json: "multer": "^1.4.5-lts.1"
const multer = require('multer');
const upload = multer({ dest: 'uploads/' });

app.post('/upload', upload.single('file'), (req, res) => {
    res.send(`File uploaded: ${req.file.originalname}`);
});

The container handles all the complex server setup, so you can focus on building your application!