DEV Community: Oluwadara Adesoji

How to Deploy and Run a NestJS App on Namecheap Shared Hosting

Oluwadara Adesoji — Fri, 03 Jul 2026 16:00:00 +0000

Deploying NestJS to Namecheap Shared Hosting is slightly different from deploying a static website or a PHP application.

NestJS must be compiled from TypeScript to JavaScript, its production dependencies must be installed, and cPanel's Node.js application manager must start it through Passenger. External services such as Redis must also be reachable from the shared server.

I learned those details while deploying a NestJS API with Bull queues, Redis, Swagger, PDF uploads, and a custom domain. This guide collects the complete working process—including the problems that initially left me with an empty deployment folder, missing build files, unavailable routes, and failed Redis connections.

How the Production Setup Works

The final request path looks like this:

Browser or API client
        |
        v
Domain and HTTPS
        |
        v
Apache / Passenger on Namecheap
        |
        v
app.js
        |
        v
dist/main.js
        |
        v
NestJS application

You do not need PM2 for this setup. Namecheap's Setup Node.js App interface and Passenger manage the application process.

Namecheap currently lets shared-hosting customers choose the Node.js version, application mode, application root, URL, startup file, and environment variables from cPanel. Its official instructions are available in How to work with Node.js App.

Prerequisites

Before starting, you need:

A Namecheap Shared Hosting account with Node.js support
A domain or subdomain assigned to the hosting account
Access to cPanel
SSH or cPanel Terminal access
A working NestJS project
A supported Node.js version compatible with the project
Production credentials for any external database, Redis server, or API

Run the application locally before deploying:

npm install
npm run start:dev

Fix local build or startup errors first. Production adds enough moving parts without bringing local errors along for the ride.

1. Prepare NestJS for Production

Listen on the port supplied by the host

Namecheap's Passenger environment controls how requests reach the application. Do not rely exclusively on a hard-coded local port.

In src/main.ts, listen on process.env.PORT with a local fallback:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  await app.listen(process.env.PORT || 4000);
}

bootstrap();

The fallback is useful locally. In production, the host-provided PORT value takes priority.

Add production scripts

Your package.json should include at least:

{
  "scripts": {
    "build": "nest build",
    "start:prod": "node dist/main.js"
  }
}

Keep runtime packages in `dependencies`

Packages needed after compilation belong in dependencies, not devDependencies.

This includes packages such as:

@nestjs/common
@nestjs/core
@nestjs/platform-express
reflect-metadata
rxjs

The Nest CLI, TypeScript, test tools, and linters can remain in devDependencies.

This distinction matters because a production-only install may omit devDependencies. The build can exist and still crash immediately if a required Nest package was classified as development-only.

2. Make the Build Produce `dist/main.js`

Namecheap runs JavaScript, not the TypeScript source directly. Compile the application:

npm run build

The expected entry file for this guide is:

dist/main.js

Use a focused tsconfig.build.json:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}

Restricting the production build to src/ prevents root-level JavaScript files such as app.js from being type-checked and emitted. It also avoids a layout such as dist/src/main.js when the desired output is dist/main.js.

Verify the build:

ls -l dist/main.js
node dist/main.js

If the application starts, stop it with Ctrl+C.

3. Create Passenger's Startup File

Create app.js in the project root:

require('./dist/main');

Your deployment should now resemble:

application-root/
├── app.js
├── package.json
├── package-lock.json
├── dist/
│   └── main.js
└── src/

Passenger conventionally looks for app.js, although cPanel also lets you specify another startup filename. The cPanel documentation likewise recommends app.js as the standard startup file: How to Install a Node.js Application.

The startup bridge is deliberately small. It loads the compiled NestJS application; it does not create a second server.

4. Decide Where to Build

There are two sensible deployment strategies.

Option A: Build locally and upload `dist`

This is usually safer on shared hosting:

npm ci
npm run build

Upload:

app.js
dist/
package.json
package-lock.json

Then install only runtime dependencies on Namecheap:

npm ci --omit=dev

This approach reduces CPU and memory usage on the shared server.

If dist/ is listed in .gitignore, a Git-only deployment will not send it. Use an artifact upload, SFTP, rsync, or another deployment step that deliberately transfers the build output.

Option B: Build on Namecheap

Upload the source and install all build dependencies:

npm ci --include=dev
npm run build
npm prune --omit=dev

This keeps dist/ out of source control but requires enough server resources to run the Nest compiler.

Choose one strategy and make it explicit. A common failure is ignoring dist/, not building on the server, and then asking Passenger to load a file that does not exist.

5. Upload the Project

You can use:

cPanel File Manager
SFTP
rsync over SSH
cPanel Git Version Control
A custom Git deployment remote

Do not upload:

Your local node_modules/
Local logs
Test coverage
Editor configuration
Development secrets

Install dependencies for the Node version selected in cPanel instead of copying node_modules from your computer. Native modules compiled on macOS, for example, may not run on the Linux hosting server.

If Git creates only a `.git` directory

If the remote folder contains .git but no application files, the pushed branch may not be the branch checked out by the server repository.

For example, the server may initialize master while you push main.

On the server:

cd ~/your-application-root
git branch -a
git checkout -f main

Replace main with the branch you actually pushed.

Renaming a local branch can also align the two sides:

git branch -m main master

The important detail is not whether the branch is called main or master; it is that the server worktree checks out the deployed branch.

6. Create the Node.js Application in cPanel

Open:

Namecheap Dashboard
→ Hosting List
→ Go to cPanel
→ Software
→ Setup Node.js App
→ Create application

Choose:

Node.js version: Match the version supported by your project
Application mode: Production
Application root: The folder containing app.js
Application URL: Your domain or subdomain
Application startup file: app.js

The application root must point to the directory that contains app.js, package.json, and dist/. Do not point it directly at dist.

Create the application.

7. Install Dependencies in the Correct Environment

The Node.js application page shows a command for entering its virtual environment through SSH. Copy and run that command exactly.

Then enter the application root:

cd ~/your-application-root

Install dependencies:

npm ci --omit=dev

If you chose to build on the server instead:

npm ci --include=dev
npm run build
npm prune --omit=dev

You can also use the Run NPM Install button in the cPanel Node.js application interface. Namecheap documents both the virtual-environment command and the cPanel install action in its Node.js App guide.

8. Configure Environment Variables

In Setup Node.js App, edit the application and add the required variables:

NODE_ENV=production
OPENAI_API_KEY=...
REDIS_URL=...
DATABASE_URL=...

Only add variables your application actually uses.

You may also use a .env file in the application root:

application-root/
├── .env
├── app.js
├── package.json
└── dist/

Do not put .env inside dist.

Protect it with .gitignore:

.env
.env.*
!.env.example

Do not put real credentials in .env.example. If a secret has ever been committed or published, removing it from the latest file is not enough—rotate the credential.

When a variable exists in both cPanel and .env, the existing process environment normally takes precedence. Make sure an old cPanel value is not overriding the current .env value.

Restart the application after changing environment variables.

9. Start or Restart the App

Return to:

cPanel → Setup Node.js App

Use Start App or Restart.

Do not keep the application alive by running npm run start:prod in an SSH terminal. The process will be disconnected from the hosting lifecycle, may conflict with Passenger, and can produce EADDRINUSE errors.

Passenger should own the production process.

For environments using a direct Passenger configuration, cPanel also documents the tmp/restart.txt mechanism. On Namecheap's managed interface, the restart button is simpler.

10. Test the Deployment

Start with a simple GET route:

https://api.example.com/v1

If you use NestJS URI versioning:

app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: '1',
});

then controller routes receive the /v1 prefix.

For example:

@Controller('api/parse-bank-statement')
export class PdfParserController {
  @Get('job/:jobId')
  getJobStatus() {}
}

becomes:

GET /v1/api/parse-bank-statement/job/:jobId

Test from a terminal:

curl -i https://api.example.com/v1

A NestJS JSON response—even a NestJS-formatted 404—proves that the request reached the application. It does not necessarily mean the proxy or deployment failed.

11. Understand Why Swagger May Return 404

Many applications intentionally disable Swagger in production:

if (process.env.NODE_ENV !== 'production') {
  setupSwaggerDocs(app);
}

In that case:

GET /docs

returns:

{
  "message": "Cannot GET /docs",
  "error": "Not Found",
  "statusCode": 404
}

That response is expected. The NestJS application is running, but the documentation route was never registered.

Do not use /docs as your only health check when production configuration disables it.

12. Read Namecheap Production Logs

Open the Passenger log configured for the application. It is often named stderr.log.

Display recent errors:

tail -n 100 stderr.log

Follow new entries:

tail -f stderr.log

Press Ctrl+C to stop following.

Find other logs:

find . -maxdepth 3 -type f -name "*.log"

Also check:

cPanel → Metrics → Errors

Namecheap says this interface displays the latest web-server error entries: cPanel control panel overview.

13. Connect External Services Carefully

A working HTTP route does not prove that Redis, a database, or another API is reachable.

For Redis-backed Bull queues, test the TCP port from Namecheap:

nc -vz <redis-host> <redis-port>

Then send a real Redis PING:

node -r dotenv/config -e 'const Redis=require("ioredis"); const r=new Redis(process.env.REDIS_URL,{connectTimeout:5000,maxRetriesPerRequest:1,retryStrategy:()=>null}); r.on("error",()=>{}); r.ping().then(console.log).catch(e=>console.error(e.code,e.message)).finally(()=>r.disconnect())'

Success returns:

PONG

If Redis works locally but Namecheap reports ECONNREFUSED or ETIMEDOUT, check:

The Redis server's firewall
Cloud security-group rules
Redis source-IP allowlists
Whether Namecheap permits the outbound destination port

In my deployment, Namecheap Support had to permit the Redis port before the production application could connect.

For the full Redis setup and debugging process, see How to Connect Redis to a Node.js App on Namecheap Shared Hosting.

14. Await Important Asynchronous Operations

Production networking exposes bugs that local development may hide.

For example, do not queue a job without awaiting the promise:

this.processPdfQueue.add(jobData);

Use:

const job = await this.processPdfQueue.add(jobData);

Without await, the controller can return “queued successfully” before Redis has accepted the job. A later unhandled rejection can also terminate the Node.js process.

Common Deployment Errors

Error or symptom	Likely cause	What to check
Only `.git` appears on the server	The pushed branch is not checked out	Run `git branch -a` and check out the deployed branch
`Cannot find module './dist/main'`	Missing build or wrong output layout	Run the build and verify `dist/main.js`
`EADDRINUSE`	Another process already uses the fallback port	Stop the manual process and let Passenger manage the app
`Cannot GET /docs`	Swagger is disabled in production	Test a real API or health route
NestJS-formatted 404	The app is running, but that route does not exist	Check version prefixes and controller paths
`MaxRetriesPerRequestError`	Redis requests repeatedly failed	Find the underlying connection error
`ECONNREFUSED` to an external service	Port closed, service stopped, or connection rejected	Test with `nc`; inspect firewalls and hosting rules
Environment variable appears stale	cPanel value overrides `.env`, or app was not restarted	Check both locations and restart
App works in terminal but not through domain	cPanel application root, URL, or startup file is wrong	Verify the Node.js App configuration
App crashes after production-only install	Runtime package is in `devDependencies`	Move runtime packages to `dependencies`

Production Checklist

Before considering the deployment complete, verify:

The application builds locally
dist/main.js exists
Root-level app.js loads ./dist/main
Runtime Nest packages are in dependencies
node_modules was installed on the server, not copied from macOS or Windows
The cPanel application root contains app.js
The cPanel startup file is app.js
The selected Node.js version matches the project
NODE_ENV is set correctly
Secrets are not committed to Git
The app was restarted after environment changes
A simple GET route works through HTTPS
Expected version prefixes such as /v1 are included
Production logs are accessible
External databases and Redis are reachable from Namecheap
Important asynchronous operations are awaited

Final Takeaway

Running NestJS on Namecheap Shared Hosting is entirely workable once the responsibilities are clear:

Nest compiles the TypeScript application into dist.
app.js gives Passenger a predictable startup file.
cPanel selects the Node version, root directory, URL, mode, and environment.
Passenger owns the process and production port.
Your deployment method must transfer or create dist.
External services must accept connections from the Namecheap server.
stderr.log tells you what happened when the browser only shows a generic error.

Most of the difficult failures were not mysterious NestJS bugs. They were boundary problems between the build, Git worktree, Passenger configuration, environment variables, and network access. Test those boundaries one at a time, and the deployment becomes much easier to reason about.

How to Connect Redis to a Node.js App on Namecheap Shared Hosting

Oluwadara Adesoji — Thu, 02 Jul 2026 13:09:01 +0000

If you deploy a Node.js application to Namecheap Shared Hosting and it uses Bull, BullMQ, sessions, caching, or another Redis-backed feature, you may discover that a Redis connection which works locally fails in production.

That happened to me. The application deployed successfully, HTTP routes worked, and environment variables loaded correctly—but every queue operation eventually failed with:

MaxRetriesPerRequestError: Reached the max retries per request limit

The underlying error was more useful:

connect ECONNREFUSED <redis-host>:<redis-port>

The fix was not installing Redis inside the shared-hosting account. Instead, I connected the Namecheap-hosted Node.js application to an external Redis server and asked Namecheap Support to permit the required outbound TCP port.

This guide walks through the complete setup and the troubleshooting lessons that mattered.

What You Are Actually Building

On shared hosting, you generally do not control the operating system or run persistent system services such as your own Redis daemon. The practical architecture is:

Browser or API client
        |
        v
Node.js app on Namecheap Shared Hosting
        |
        | Outbound TCP connection
        v
External Redis server

The Redis server can be:

A managed Redis service
Redis running on a VPS or cloud server you control
Another externally reachable Redis-compatible service

The important requirement is that Namecheap's server must be able to reach the Redis host and port.

Prerequisites

You will need:

A Node.js application configured through cPanel → Setup Node.js App
SSH or cPanel Terminal access
An external Redis instance
The Redis hostname, port, username, password, and TLS requirements
A Redis client such as ioredis

Namecheap's official guide explains how to create the Node.js application, choose its root and startup file, add environment variables, install packages, and restart it: How to work with Node.js App.

1. Create or Obtain an External Redis Instance

Create a Redis database with your chosen provider, or configure Redis on a separate server.

Your provider should give you a connection URL resembling one of these:

redis://default:PASSWORD@HOST:PORT

For a TLS-encrypted connection:

rediss://default:PASSWORD@HOST:PORT

redis:// uses a normal TCP connection. rediss:// tells compatible clients to use TLS. Use the exact scheme supplied by your Redis provider; do not change it by guesswork.

Do not use a provider's HTTP REST URL:

https://example-redis-provider.com

Bull and ioredis require the Redis TCP endpoint.

Secure the Redis server

Never expose an unauthenticated Redis instance to the public internet. Redis warns that an exposed server can allow destructive commands such as FLUSHALL. Use authentication, network restrictions, and TLS where available. See the official Redis security guidance.

If your provider has an IP allowlist, you may need the outgoing public IP of the Namecheap server. From the Namecheap terminal, run:

curl -s https://api.ipify.org

Add that IP to the Redis provider's allowlist. Do not use 0.0.0.0/0 merely to make the connection work.

2. Configure the Node.js Application

For a NestJS application using Bull, install the required packages:

npm install @nestjs/bull bull ioredis

Configure Bull with the connection URL:

import { BullModule } from '@nestjs/bull';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    BullModule.forRoot({
      redis: process.env.REDIS_URL,
    }),
  ],
})
export class AppModule {}

For a plain Node.js connection test:

const Redis = require('ioredis');

const redis = new Redis(process.env.REDIS_URL);

redis.ping().then(console.log);

3. Add `REDIS_URL` in cPanel

Open:

cPanel → Setup Node.js App → Edit application

Under Environment variables, add:

Name:  REDIS_URL
Value: redis://default:PASSWORD@HOST:PORT

Use rediss:// if your provider requires TLS.

You may also keep a .env file in the application root:

application-root/
├── app.js
├── package.json
├── .env
└── dist/

The .env file belongs beside app.js and package.json, not inside dist.

Do not commit .env to Git. Add it to .gitignore:

.env
.env.*
!.env.example

If the same variable exists in both cPanel and .env, the value already present in the process environment normally wins. A blank or outdated cPanel value can therefore override the correct value in .env.

After adding or changing environment variables, restart the application from Setup Node.js App.

4. Confirm That the Environment Variable Loads

From the application root in the Namecheap terminal, run this safe check:

node -r dotenv/config -e 'const v=process.env.REDIS_URL; console.log({set:Boolean(v), protocol:v ? v.split(":")[0] : null, length:v ? v.length : 0})'

Example output:

{ set: true, protocol: 'redis', length: 107 }

This confirms that the .env value exists without printing the password.

One subtlety: environment variables configured in cPanel are injected into the Passenger-managed application process. They may not automatically appear in an ordinary SSH shell. The command above explicitly reads the .env file through dotenv.

5. Test the Network Before Testing the Application

First test whether the Redis TCP port is reachable:

nc -vz <redis-host> <redis-port>

Possible results include:

Connection succeeded

or:

Connection refused

A normal ICMP ping is not enough. It only tests whether a host responds to ICMP; it does not prove that Redis is listening or reachable on its TCP port.

Next, test the Redis protocol using the same client library as the application:

node -r dotenv/config -e 'const Redis=require("ioredis"); const r=new Redis(process.env.REDIS_URL,{connectTimeout:5000,maxRetriesPerRequest:1,retryStrategy:()=>null}); r.on("error",()=>{}); r.ping().then(x=>console.log("Redis:",x)).catch(e=>console.error(e.code,e.message)).finally(()=>r.disconnect())'

A successful connection prints:

Redis: PONG

The Redis PING command is specifically intended for testing whether a connection is alive. See the official PING command documentation.

If redis-cli is available, you can also use:

redis-cli -u "$REDIS_URL" PING

Redis documents URI-based connections and notes that rediss is the scheme for TLS: Redis CLI documentation.

6. When It Works Locally but Fails on Namecheap

This was the key production issue in my deployment:

The Redis test returned PONG on my local machine.
The same connection returned ECONNREFUSED from the Namecheap terminal.
The environment variable was present and correctly formatted.
Namecheap Support opened the required outbound port.
The connection then worked from production.

If you encounter the same pattern, first check:

Whether the Redis provider allowlists source IP addresses
Whether your Redis server's firewall permits the Namecheap server
Whether a cloud security group permits the Redis port
Whether Redis is actually listening on the advertised external interface and port
Whether Namecheap permits outbound TCP traffic to that destination port

If the destination-side settings are correct, contact Namecheap Support with a precise request:

Please confirm whether outbound TCP connections from my shared-hosting server to <redis-host>:<redis-port> are permitted. My Node.js application requires this connection for Redis.

Include:

Your Namecheap shared-server hostname
The destination Redis hostname or IP
The destination TCP port
The exact error, such as ECONNREFUSED or ETIMEDOUT

Never include your Redis password in the support message.

7. Configure Queue Operations to Fail Safely

Redis connectivity is not the only concern. Make sure asynchronous queue operations are awaited.

Avoid this:

this.processPdfQueue.add(jobData);

return {
  message: 'Job queued successfully',
};

If Redis is unavailable, the application may report success before the rejected promise is observed. In some Node.js configurations, the unhandled rejection can terminate the process.

Use:

const job = await this.processPdfQueue.add(jobData);

return {
  message: 'Job queued successfully',
  jobId: job.id,
};

Now the surrounding try/catch can return an honest error response when Redis is unavailable.

Do not treat a larger maxRetriesPerRequest value as the fix for an unreachable Redis server. More retries only postpone the same failure.

8. Read Production Logs

For a Namecheap Node.js application, application and Passenger errors commonly appear in the configured log file, often named stderr.log.

Display recent entries:

tail -n 100 stderr.log

Follow new entries:

tail -f stderr.log

Press Ctrl+C to stop following the file.

You can also inspect:

cPanel → Metrics → Errors

Namecheap documents that this view shows the latest web-server errors in its cPanel overview.

Common Redis Connection Errors

Error	What it usually means
`ECONNREFUSED`	The host was reached, but the port rejected the connection or nothing was listening
`ETIMEDOUT`	A firewall, security group, routing problem, or unreachable host silently dropped the connection
`ENOTFOUND`	The Redis hostname could not be resolved
`WRONGPASS` or authentication error	The username or password is wrong
TLS or socket reset errors	The client and server may disagree about TLS; verify `redis://` versus `rediss://`
`MaxRetriesPerRequestError`	The client retried a failed request repeatedly; inspect earlier logs for the underlying connection error

Deployment Checklist

Before calling the setup complete, verify all of the following:

[ ] Redis is running on an external, reachable server
[ ] Authentication is enabled
[ ] TLS is enabled when supported
[ ] REDIS_URL uses the provider's TCP endpoint
[ ] .env is outside dist and excluded from Git
[ ] The cPanel environment variable is correct
[ ] The Node.js app was restarted after configuration changes
[ ] nc -vz <host> <port> succeeds from Namecheap
[ ] The ioredis test returns PONG from Namecheap
[ ] Redis allows the Namecheap server's source IP where allowlisting is used
[ ] Namecheap permits the required outbound destination port
[ ] Queue operations such as queue.add() are awaited
[ ] Production logs are available and monitored

Final Takeaway

The hardest part was not the Node.js or Bull configuration. It was identifying where the connection failed.

Checking the problem layer by layer made the answer clear:

Confirm the environment variable exists.
Confirm the URL is a Redis TCP URL.
Test the destination port from the production terminal.
Run a real Redis PING.
Compare local and production results.
Check both destination firewalls and Namecheap's outbound rules.

Once Namecheap permitted the required outbound port, the application connected to Redis and the background jobs started working.

DEV Community: Oluwadara Adesoji

How to Deploy and Run a NestJS App on Namecheap Shared Hosting

How the Production Setup Works

Prerequisites

1. Prepare NestJS for Production

Listen on the port supplied by the host

Add production scripts

Keep runtime packages in dependencies

2. Make the Build Produce dist/main.js

3. Create Passenger's Startup File

4. Decide Where to Build

Option A: Build locally and upload dist

Option B: Build on Namecheap

5. Upload the Project

If Git creates only a .git directory

6. Create the Node.js Application in cPanel

7. Install Dependencies in the Correct Environment

8. Configure Environment Variables

9. Start or Restart the App

10. Test the Deployment

11. Understand Why Swagger May Return 404

12. Read Namecheap Production Logs

13. Connect External Services Carefully

14. Await Important Asynchronous Operations

Common Deployment Errors

Production Checklist

Final Takeaway

How to Connect Redis to a Node.js App on Namecheap Shared Hosting

What You Are Actually Building

Prerequisites

1. Create or Obtain an External Redis Instance

Secure the Redis server

2. Configure the Node.js Application

3. Add REDIS_URL in cPanel

4. Confirm That the Environment Variable Loads

5. Test the Network Before Testing the Application

6. When It Works Locally but Fails on Namecheap

7. Configure Queue Operations to Fail Safely

8. Read Production Logs

Common Redis Connection Errors

Deployment Checklist

Final Takeaway

Keep runtime packages in `dependencies`

2. Make the Build Produce `dist/main.js`

Option A: Build locally and upload `dist`

If Git creates only a `.git` directory

3. Add `REDIS_URL` in cPanel