Introduction to the Automated Deployment Process of iKnowABit Based on Next.js | Technical Architecture

Our website (iKnowABit) is developed based on the Next.js framework. Without introducing heavyweight CI/CD tools (such as Jenkins or GitLab CI), we have implemented a lightweight, zero-downtime automated deployment process with automatic fault rollback capabilities using native Shell scripts combined with PM2 and Node.js.

This article will detail the design philosophy of this deployment process, the pain points it addresses, and the specific underlying technical mechanisms.

1. Pain Points and Requirements Analysis

When using native scripts to deploy a Next.js full-stack project, you typically encounter the following technical pain points:

1. Service Interruption: Executing source code pulls and dependency installations directly in the production directory will render the service unavailable during the build process.
2. State Pollution and Difficult Rollbacks: If dependency installation fails or database migration throws an error, the production environment is left in a corrupted intermediate state, making manual recovery highly costly.
3. Concurrent Management of Multiple SQLite Databases: The underlying architecture of this project uses multiple independent SQLite database files to separate business lines. Manually executing schema migrations can easily lead to omissions or file lock conflicts.
4. Server Resource Consumption: Running a full-fledged Webhook listening service locally on the server consumes additional memory and port resources.

2. Architecture Design and Core Mechanisms

To address the aforementioned pain points, we designed an architecture featuring "Lightweight Polling Monitoring + Atomic Symlink Release + Automatic Fault Cleanup".

• Lightweight Monitoring: Utilizes the scheduled task system combined with remote Hash reading commands to determine if there is an update on the server side without downloading the full codebase.
• Atomic Deployment: Each deployment generates an independent timestamped directory. Code pulls and dependency installations are performed in this isolated directory, and the application version is ultimately updated by switching the symlink.
• Seamless Reloading: Based on PM2's graceful reload feature, the Node process is automatically restarted after the symlink switch, ensuring that online user requests are not interrupted.
• Secure Rollback Mechanism: Catches abnormal signals via the Bash process. Any non-zero exit code encountered during the deployment immediately triggers the automatic deletion of the current build directory, preventing any pollution to the stable production environment.

Overall Automated Deployment Flowchart

Loading diagram...

3. Core Implementation Principles

The entire deployment architecture is driven collaboratively by the monitoring module, the deployment module, and the multi-database migration module. To thoroughly strip away sensitive information, the following sections focus on analyzing the low-level operational logic of each module.

3.1 Monitoring Trigger Module

This module is called at a high frequency through the system's scheduled tasks. To ensure concurrency safety and performance, specific optimization strategies are adopted.

Loading diagram...

• Concurrency Lock Control: Before each execution, it checks for and generates a process lock file in a temporary directory. If the lock file is detected to have remained beyond a set threshold (e.g., 20 minutes), it is deemed a deadlock and forcibly released to prevent the monitoring task from hanging permanently.
• Ultra-Fast Version Comparison: It abandons full code-pulling commands that consume bandwidth and disk I/O, replacing them with timeout-configured, read-only network requests to directly obtain the remote repository's pointer Hash value and compare it with the locally recorded file. Only when a difference is detected does it trigger the downstream release process.

3.2 Deployment and Rollback Module

This module serves as the core execution engine responsible for completing the atomic release, with its core features being fault tolerance and environmental isolation.

Loading diagram...

• Strict Exception Handling and Automatic Rollback: The module runs in strict mode, immediately throwing an exception if any intermediate command (such as dependency installation or network timeout) fails. Simultaneously, it registers exit hooks (Traps). When an abnormal termination signal is received and the success flag has not been set, it automatically executes cleanup logic to destroy the currently incomplete and fragmented directory.
• Decoupling of Data and Code: Persistent data (such as independent SQLite database files for each business line and their Write-Ahead Logging caches) and user static resources are stored in absolute, physical shared paths. During each deployment, symlinks pointing to these physical paths are created within the new version's directory, ensuring a complete separation of code updates from data states.
• Zero-Downtime Switching and Old Version Cleanup: After all preparatory work (dependency installation, data mounting) is completed in an isolated directory, the production entry point is instantaneously redirected to the new directory by resetting the symlink, followed by invoking the daemon to refresh the configuration. Finally, an automatic cleanup command deletes older directories in reverse chronological order, retaining only a very small number of historical versions to free up server disk space.

3.3 Multi-Database Migration Module

A multi-database automated migration module built on Node.js scripts and Drizzle ORM, responsible for resolving cross-business synchronization of underlying table structure changes.

Loading diagram...

• Multi-Database Mapping Management: The module maintains a mapping matrix internally, including the names, absolute physical file paths, and pre-compiled SQL migration script paths for multiple entity databases like the core business DB, system configuration DB, and content DB. In an independent execution environment, it loads global environment variables on demand and initializes the corresponding connection pools.
• State Synchronization and Security Blocking: It strictly iterates and executes the structure upgrade tasks for each database. If any SQL-level error or table structure conflict occurs during this process, it immediately catches the exception, safely severs the current file's connection lock, and forces the process to exit with a non-zero status code. This abnormal status code is caught by the strict mode of the outer monitoring system, directly blocking the application layer's reload behavior and triggering the automatic cleanup rollback of the physical directory, thereby ensuring that the data structures relied upon by the older version of the service remain intact.

---

When troubleshooting large chunks of parameter logs generated by the aforementioned architecture deployment, or when independently debugging deep configuration files related to business logic, we recommend using the following system troubleshooting auxiliary tool:

🔗 Local Pure Frontend JSON Validator and Parser

Provides instant syntax error highlighting and visual tree search interaction, computing formatting entirely within the local browser memory without leaking sensitive parameters to the cloud.

→

---

This article is originally created by the iKnowABit team. Technical support: Automated release strategy built on Next.js, conventional Bash cluster architecture, and Drizzle ORM.