HTMLSCribe Documentation

HTMLScribe SaaS Documentation

Introduction

Welcome to the documentation for HTMLScribe SaaS. This guide will help you set up and use our application, which is built with Laravel 11 and uses Vite for asset compilation. The system also includes a Node.js application used for generating PDFs and images.

System Requirements

Important: Please keep in mind that this system will not work on shared hosting as some of the required libraries for the Node.js server need root access for installation.

For Laravel Application:

PHP >= 8.2.12 or above
Laravel 11.0.0 or above
Composer 2.3.7 or above
Node.js (v18.X) or above
MySQL 5.7+ or above

PHP Extensions:

BCMath
Ctype
JSON
Mbstring
OpenSSL
PDO
Tokenizer
XML
Fileinfo
Sodium Extension
GD
Zip

In most servers, these extensions are enabled by default, but you should check with your hosting provider.

Services:

Database: MySQL
Cache: Database
Queue: Database
Session: Database
Mail: SMTP

For Node.js Application:

Node.js (v18.X or above)
npm or yarn
libxfixes3, libxkbcommon0, libnss3, libatk1.0-0, libatk-bridge2.0-0, libcups2, libxcomposite1, libxrandr2, libxdamage1, libgbm1, libasound2, libpango1.0-0, libcairo2

Database Configuration

Before starting the admin installation, you must configure the database for the application.

The exact steps might vary slightly depending on your hosting provider. If you encounter any difficulties, please contact your server provider.

Important: Make sure to securely store your database credentials. You'll need them for the next steps of the installation process.

Steps to Create and Configure the Database

Go to MySQL Databases
Create a New Database
Create a Database User
Add the User to the Database
Assign User Privileges

Local Setup

Setting up the Laravel Application

Extract the ZIP file containing the project to your desired location
Navigate to the project directory and open the terminal
Install PHP dependencies:
```
composer install
```
Generate an application key:
```
php artisan key:generate
```

Create a local database and configure it in the .env file:

                                        DB_CONNECTION = mysql
                DB_HOST = localhost
                DB_PORT = 3306
                DB_DATABASE = DATABASE_NAME
                DB_USERNAME = root
                DB_PASSWORD =

Import the database htmlscribedb.sql file to the created database
Update the application URL in .env:
```
APP_URL=your_domain_url
```
Update the Node API URL in .env:
```
NODE_API_URL=your_sub_domain_url
```
Install Node.js dependencies:
```
npm install
```
Compile assets:
```
npm run dev
```
Start the development server:
```
php artisan serve
```
Storage Linking (optional):
If images aren't showing, ensure the public/storage folder exists; if not, run:
```
php artisan storage:link
```

Local Setup for Node.js API Server

Upload HtmlScribefunctions.zip to your chosen directory and extract it.

Update BASE_URL and LARAVEL_API_URL in .env:

BASE_URL=your_local_url_of_nodejs_api_server

LARAVEL_API_URL=your_local_url_of_admin_dashboard

Install Node.js dependencies and start the server:
```
npm install
```
```
node app.js
```

Server Setup

After downloading the code from Codester or any Marketplace, upload the HtmlScribe.zip file to your server directory and extract it. HTMLScribe can be installed on your main domain or subdomain, e.g, yourdomain.com or subdomain.yourdomain.com.

Note: HtmlScribe (Laravel) and HtmlScribeFunctions (Nodejs) must be on different domain/subdomain. They cannot be on the same domain/subdomain.

Server Setup for Laravel Admin Dashboard

Important: Step 1 to 5 should be done locally.

Uploading to cPanel:

Create a database on your server and add the database credentials to the .env file:

DB_CONNECTION=mysql
                DB_HOST=127.0.0.1
                DB_PORT=3306
                DB_DATABASE=DATABASE_NAME
                DB_USERNAME=DATABASE_USERNAME
                DB_PASSWORD=DATABASE_PASSWORD

Update APP_URL in .env with the URL where you uploaded HtmlScribe:
```
APP_URL=your_domain_url
```
Update NODE_API_URL in .env with the URL for HtmlScribeFunctions:
```
NODE_API_URL=your_sub_domain_url
```

Update APP_NAME, APP_ENV, and APP_DEBUG:

APP_NAME=Your Saas Name
                APP_ENV=production
                APP_DEBUG=false

Open the dashboard directory and install Node.js dependencies:
```
npm install
                npm run build
```
No need to copy the node_modules folder to the server.
Log in to your cPanel account and navigate to the File Manager.
Upload the dashboard to your desired directory.
Import the database htmlscribedb.sql file to the database you created.
Install PHP dependencies:
```
composer install
```
Generate the Scribe documentation:
```
php artisan scribe:generate
```
Storage Linking:
```
php artisan storage:link
```

Important: Run necessary Laravel commands via SSH or cPanel’s terminal.

You can watch this video for Nodejs. The video installation is using Vps terminal but you will get the basic idea Watch Video

Server Setup for Node.js API Server

Upload HtmlScribefunctions.zip to your desired directory:
- Connect to your server using cPanel or Plesk's file manager, or via FTP.
- Navigate to the directory and extract HtmlScribefunctions.zip.

Update BASE_URL and LARAVEL_API_URL in .env:

BASE_URL=your_nodejs_api_url
                LARAVEL_API_URL=your_admin_dashboard_url

Install Node.js dependencies via terminal:
```
npm install
```
Install libraries required for screenshot and PDF generation:
```
sudo apt-get update
                                sudo apt-get install -y libxfixes3 libxkbcommon0 libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxcomposite1 libxrandr2 libxdamage1 libgbm1 libasound2 libpango1.0-0 libcairo2
                                
```
Run node test.js If it shows Chromium launched successfully. then it is almost set and if you run into some errors, you need to look into it whether its asking for missing library (install it) or some error like
Error: Could not find Chrome (ver. 127.0.6533.72). This can occur if either you did not perform an installation before running the script (e.g. `npx puppeteer browsers install chrome`) or your cache path is incorrectly configured (which is: C:\Users\Kamaldeep\.cache\puppeteer). For (2), check out our guide on configuring puppeteer at https://pptr.dev/guides/configuration.
If the error is like this then you need to run
```
npx puppeteer browsers install chrome
```
Set app.js as the server entry point:
- In cPanel, go to "Setup Node.js App" and set the correct environment.
- In Plesk, go to "Hosting Settings" and set app.js as the startup file.

Info: Refer to troubleshooting if PDF and image generation does not work.

System Configuration

These configurations are crucial for HTMLScribe to function correctly. Please follow each step carefully.

Email Configuration

Navigate to: Left Sidebar -> Settings -> Mail
Setting up Email:
- Choose your mail driver/mailer (SMTP recommended for reliability)
- Enter your SMTP server/Mail Host address (e.g., smtp.gmail.com for Gmail)
- Set the SMTP port (usually 587 for TLS or 465 for SSL)
- Enter your email username and password
- Set encryption type (TLS or SSL, depending on your mail server)
- Enter the "From" email address and name for outgoing emails
After configuring, use the "Send Test Email" feature to ensure everything is working correctly.
Payment Configuration (Stripe, Paypal, and Paddle)

Navigate to: Left Sidebar -> Settings -> Payment
Setting up Stripe, PayPal, & Paddle Subscriptions with Webhooks:
- Enter your Stripe, PayPal, and Paddle API keys in HTMLScribe settings
- Set up Stripe Webhook:
  1. Go to Stripe Dashboard -> Developers -> Webhooks
  2. Add endpoint: https://your-domain.com/stripe/webhook
  3. Select events: invoice.payment_succeeded, invoice.payment_failed, charge.refunded, customer.subscription.deleted
  4. Copy Webhook Secret to HTMLScribe
- Set up PayPal Webhook:
  1. Go to PayPal Dashboard -> Developer -> Webhooks
  2. Add endpoint: https://your-domain.com/paypal/webhook
  3. Select events: PAYMENT.SALE.COMPLETED, SUBSCRIPTION.PAYMENT.FAILED, SALE.REFUNDED, SUBSCRIPTION.SUSPENDED, SUBSCRIPTION.CANCELLED
  4. Copy Webhook ID to HTMLScribe
- Set up Paddle Webhook:
  1. Go to your Paddle Dashboard -> Developer Tools-> Notification
  2. Add endpoint: https://your-domain.com/paddle/webhook
  3. Select events: subscription.activated, subscription.updated, subscription.canceled, subscription.past_due, subscription.paused, transaction.completed, transaction.payment_failed, adjustment.updated
  4. Copy the Webhook ID to HTMLScribe
Test subscriptions to ensure proper setup.
Cron Job and Queue Process Configuration

1. Cron Job Setup

Navigate to: Left Sidebar -> Settings -> CronJob
Setting up Cron Job:
1. Copy the cron command displayed in the settings
2. Access your server's cron job manager (often found in cPanel or through SSH)
3. Create a new cron job and paste the copied command
4. Set the cron job to run every minute: * * * * *
The cron job is essential for processing scheduled tasks, such as sending emails, updating subscription statuses, and resetting credits.
2. Queue Process Setup
Setting up Queue Worker:

Choose one of the following methods to process queued jobs:

Option A: Supervisor (Recommended for Production)
1. Install Supervisor on your server
2. Create a new Supervisor configuration file for your queue worker
3. Add the following command to your Supervisor config:
php /path/to/your/project/artisan queue:work --tries=3 --max-time=3600
Adjust the path, tries, and max-time as needed for your application.

Option B: Manual Long-Running Process

If you can't use Supervisor, you can run the queue worker as a long-running process:
nohup php /path/to/your/project/artisan queue:work > /dev/null 2>&1 &
Note: This method requires manually restarting the process if it stops.

The queue worker processes background jobs such as sending emails, generating reports, and other time-consuming tasks to improve application responsiveness.

Important: Accurate configuration is crucial for the system's proper functioning. Double-check all entries before saving. If you encounter any issues, please consult our support documentation or contact our support team at [email protected].

Tip: After completing these configurations, perform a thorough test of the system, including creating a test subscription, to ensure all components are working together correctly.

Zapier Configuration

Important: These zapier configurations are crucial for Zapier integration to function correctly. Please follow each step carefully.

Note: I have added images to help you create Zapier Application. But you must have some knowledge of what you are doing.
First you need to visit Zapier Developer. Create a developer account if you don't have an account.

Create a new app

After adding the required details, click the "Create" button to create the app.
Info: At Start you can select Private for Intented Audience and later change it to Public when everything is working fine.
Authentication for APP

After creating the app, next step is to setup Authentication for it. Select API KEY and click save
Add Field for Authentication

Click on the Add Fields
Add Details to the Field for Authentication

After adding the details click on Add
Go to Advanced

On the Left side click on Advanced and choose Request Template in tab and then HTTP Headers. Update the field if it exist to match to one in below image. If it does not exists make sure you have done the above steps correctly.
Go back to Authentication

Edit it and go to Step 2. Add url like https://yourdomain.com/api/zapier/auth-test as a GET request, the yourdomain.com is the domain where you have uploaded dashboard. Click Save & Continue.
Step 3 in Authentication - a

Go to Step 3. Click on account where it will show a popup where you will need to add an api key. You can create a demo user and create api for that user. Then click Test Authentication.
Step 3 in Authentication - b

After clicking Test Authentication if you get this response. It means things are going correctly. If not then look at the above steps if you have missed something.
Create Action

Click Actions on the left side panel and create a new action. Fill the details like in the image and save it. Do it twice. One for PDF and for Image like in the images below
Edit Action

Edit Actions one by one and in Input Designer tab to add all the fields/atrributes. You can find all the fileds for PDF and Image within API Documentation. Some are required fields and some are optional. Make sure to mark the required fields as Required when adding.

Important: Make Sure the Keys matches the exact names in the API docs..
Edit Action

Edit Actions one by one and in API Configuration tab. Add url like https://yourdomain.com/api/zapier/generate-image for the Image Action and https://yourdomain.com/api/zapier/generate-pdf for PDF action as a POST request, the yourdomain.com is the domain where you have uploaded dashboard.

Click Show Options and go to HTTP Headers to add another field with key as From and value as zapier. Like in the second image. Make sure it matches. It is case sensitive. Click Save API Request & Continue.

Now go to below step 3 and add the data in the last image for both actions. Click Save Output & Finish.

Note: You are now almost done.
Add top there might be Create a Zap button. You can click it to create test automation for the image and PDF. If it's sending a proper response. It means everything is setup correctly. If not then look into the steps again.

Updating

Before Updating, make sure you know what you are doing and keep a backup copy just in case.
We will not be responsible for any issues

For updating the admin panel extract it locally and run the commands just like for the new install and then make a zip and upload the zip file in your project root folder and extract it. But make sure to make env and other changes if needed.

For updating the nodejs just upload your HtmlScribeFunctions.zip file in your project root folder and extract it. But make sure to make env and other changes if needed.

In some cases you might need to run php artisan migrate

Update after Customisation

If you customized something on the code and want to update to our latest version, follow any option given below:

First, push your code on a git branch. Then download our project code from Codester or any Marketplace and push it to another branch. At last, merge both branches, and it is possible to get conflicts on the branch. Resolve them carefully.

Download the updated version from Codester or any Marketplace and do your customization again.

API Documentation Setup

HTMLScribe uses Laravel Scribe to generate API documentation. Follow the instructions below to make changes to the documentation and regenerate it.

1. Customization Options

If you need to update the introduction or examples section, you can modify the following files:

Introduction: Modify the content in public/assets/img/examples/examples.md.
Images: Replace or add images in the public/assets/img/examples/ directory.

2. Configuration Settings

Changes to the Scribe configuration, such as formatting or output options, can be made in the scribe.php config file located in your Laravel config/ folder.

3. Regenerate Documentation

After making changes to the configuration or content, follow these steps to regenerate the documentation:

Clear Laravel cache:

php artisan config:clear
                php artisan view:clear
                php artisan cache:clear

Generate the Scribe documentation:
```
php artisan scribe:generate
```

4. Post-Generation Adjustments (optional)

After generating the documentation,if favicon is not showing. Add the line to resources/views/scribe/index.blade.php in the head section:

<link rel="icon" type="image/png" href="{{ asset('assets/img/favicon/favicon.ico') }}">

Localization Setup

To update or add new languages in this project, follow these steps:

1. Updating Existing Languages

Modify language JSON files in the project/lang directory to update the content. The main files are:

project/lang/en.json - English
project/lang/es.json - Spanish
project/lang/fr.json - French
project/lang/ar.json - Arabic
project/lang/hi.json - Hindi

2. Adding a New Language

To add a new language:

Create a new JSON file in project/lang with the language code as the filename. For example, to add Dutch, create nl.json.
Copy the content from en.json into the new file and translate each key-value pair.

3. Register the Language

Update the following files to register the new language:

app/Http/Controllers/Language/LanguageController.php - Add the new language code here.
app/Http/Middleware/LocaleMiddleware.php - Register the language in middleware.
project/resources/views/layouts/sections/navbar/navbar.blade.php - Update the navbar with the new language option.
navbar-front.blade.php - Also update the front navbar for consistency.

Note: Make sure the language JSON file and code added in controllers, middleware, and navbars match exactly to ensure proper functionality.

Troubleshooting

If you encounter any issues while setting up or using the system, please refer to the following common problems and their solutions:

Issue: Unable to install Puppeteer dependencies or if screenshot/pdf generation does not work
Solution: Ensure you have the necessary system libraries installed. On Ubuntu, you can run:
```
sudo apt-get install -y libxfixes3  libxkbcommon0 libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxcomposite1 libxrandr2 libxdamage1 libgbm1 libasound2 libpango1.0-0 libcairo2
```
Issue: Image and pdf generation are not working If image and pdf generation are not working you can go your project location in terminal and run
```
node test.js
```
It will provide you with an overview of the issue(s) or missing libraries.
Issue: If you are facing any issues regarding the permissions, then you need to run the following command in your project directory
Solution:
```
sudo chmod -R o+rw bootstrap/cache
sudo chmod -R o+rw storage
```
Issue: Laravel application returns a 500 error
Solution: Check your Laravel log files in storage/logs for more detailed error information. Ensure your .env file is correctly configured and all required PHP extensions are installed.
Issue: Node.js application crashes or doesn't start
Solution: Check if all required environment variables are set correctly. Ensure you have the correct Node.js version installed and all dependencies are up to date.

HTMLScribe SaaS Documentation

Introduction

System Requirements

For Laravel Application:

PHP Extensions:

Services:

For Node.js Application:

Database Configuration

Steps to Create and Configure the Database

Go to MySQL Databases

Create a New Database

Create a Database User

Add the User to the Database

Assign User Privileges

Local Setup

Setting up the Laravel Application

Local Setup for Node.js API Server

Server Setup

Server Setup for Laravel Admin Dashboard

Uploading to cPanel:

Server Setup for Node.js API Server

System Configuration

Email Configuration

Setting up Email:

Payment Configuration (Stripe, Paypal, and Paddle)

Setting up Stripe, PayPal, & Paddle Subscriptions with Webhooks:

Cron Job and Queue Process Configuration

1. Cron Job Setup

Setting up Cron Job:

2. Queue Process Setup

Setting up Queue Worker:

Option A: Supervisor (Recommended for Production)

Option B: Manual Long-Running Process

Zapier Configuration

Create a new app

Authentication for APP

Add Field for Authentication

Add Details to the Field for Authentication

Go to Advanced

Go back to Authentication

Step 3 in Authentication - a

Step 3 in Authentication - b

Create Action

Edit Action