How to Deploy Kutt on Rocky Linux Release 9.4 (Blue Onyx)

Deploying the Kutt URL shortener on Rocky Linux 9.4 (Blue Onyx) involves several steps, from setting up your server environment to configuring Docker and troubleshooting potential issues. This guide provides a comprehensive walkthrough based on personal experience to help you get Kutt up and running smoothly.

Prerequisites

A Rocky Linux 9.4 server: Ensure you have access to a server running Rocky Linux 9.4.
Root or sudo access: You need administrative privileges to install packages and configure the system.
Basic knowledge of Docker and Docker Compose: Familiarity with Docker is essential for this deployment.

Step 1: Update Your System

First, make sure your server is up to date.

sudo dnf update -y

Step 2: Install Required Packages

Install Docker, Docker Compose, and other necessary packages.

sudo dnf install -y docker docker-compose git

Start and enable Docker service.

sudo systemctl start docker
sudo systemctl enable docker

Step 3: Clone the Kutt Repository

Clone the Kutt repository from GitHub.

git clone https://github.com/thedevs-network/kutt.git
cd kutt

Step 4: Configure Environment Variables

Create a .env file in the root of your cloned repository and add the following configuration. Replace placeholders with your actual values.

# .env file

# General settings
PORT=3000
NODE_ENV=production
SITE_NAME=Kutt
DEFAULT_DOMAIN=yourdomain.com
JWT_SECRET=your_jwt_secret

# PostgreSQL settings
DB_HOST=postgres
DB_NAME=kutt
DB_USER=postgres
DB_PASSWORD=your_postgres_password

# Redis settings
REDIS_HOST=redis

# Gmail SMTP settings
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_SECURE=false
MAIL_USER=your_gmail_address@gmail.com
MAIL_PASSWORD=your_app_password

# URL length
LINK_LENGTH=6

# Google Safe Browsing API (optional)
# GOOGLE_SAFE_BROWSING_KEY=

# Recaptcha (optional)
# RECAPTCHA_SECRET_KEY=
# RECAPTCHA_SITE_KEY=

# Google Analytics (optional)
# GA_TRACKING_ID=

Step 5: Configure Docker Compose

Create or modify the docker-compose.yml file to include the necessary services.

version: "3"

services:
  kutt:
    image: kutt/kutt
    depends_on:
      - postgres
      - redis
    command: ["./wait-for-it.sh", "postgres:5432", "--", "npm", "start"]
    ports:
      - "3000:3000"
    env_file:
      - .env
    networks:
      - kutt_network

  redis:
    image: redis:6.0-alpine
    volumes:
      - redis_data:/data
    networks:
      - kutt_network

  postgres:
    image: postgres:12-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your_postgres_password
      POSTGRES_DB: kutt
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - kutt_network

volumes:
  redis_data:
  postgres_data:

networks:
  kutt_network:
    driver: bridge

Step 6: Modify Kutt Source Files

You may need to add logging and troubleshooting code. For example, in server.ts, add logging for signup errors.

// server/handlers/auth.ts

export const signup: Handler = async (req, res) => {
  console.log(`Signup request received: ${JSON.stringify(req.body)}`);
  try {
    const salt = await bcrypt.genSalt(12);
    const password = await bcrypt.hash(req.body.password, salt);

    const user = await query.user.add(
      { email: req.body.email, password },
      req.user
    );

    await mail.verification(user);

    return res.status(201).send({ message: "Verification email has been sent." });
  } catch (error) {
    console.error(`Error during signup: ${error.message}`);
    return res.status(500).send({ message: "Failed to signup. Please try again later." });
  }
};

Step 7: Build and Start Docker Containers

Build and start your Docker containers.

sudo docker-compose build
sudo docker-compose up -d

Step 8: Configure Firewall

Ensure your firewall allows traffic on the necessary ports.

sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=5432/tcp
sudo firewall-cmd --permanent --add-port=6379/tcp
sudo firewall-cmd --permanent --add-port=587/tcp
sudo firewall-cmd --reload

Step 9: Test the Deployment

Access the Kutt web interface: Open your browser and navigate to http://yourdomain.com:3000.
Signup and verify: Register a new account and verify the email using the link sent to your email.

Troubleshooting

SMTP Issues: If you encounter SMTP connection issues, ensure the firewall settings are correct and the SMTP credentials are accurate.

Database Connection: Verify PostgreSQL and Redis services are running and accessible from the Kutt container.

Logs: Check Docker logs for errors.

sudo docker logs st-kutt-1
sudo docker logs st-postgres-1
sudo docker logs st-redis-1

Additional Changes

You might need to adjust some configurations in your package.json to ensure dependencies are installed correctly.

{
  "name": "kutt",
  "version": "2.7.4",
  "scripts": {
    "start": "npm run migrate && cross-env NODE_ENV=production node production-server/server.js",
    "migrate": "knex migrate:latest --env production",
    "build": "rimraf production-server && tsc --project tsconfig.json && copyfiles -f 'server/mail/*.html' production-server/mail && next build client/"
  },
  "dependencies": {
    "bcryptjs": "^2.4.3",
    "cross-env": "^7.0.3",
    "express": "^4.17.1",
    "knex": "^0.95.4",
    "mail": "^1.0.0",
    "next": "10.0.5",
    "nodemailer": "^6.6.3",
    "pg": "^8.5.1",
    "rimraf": "^3.0.2",
    "ts-node": "^9.1.1",
    "typescript": "^4.1.3"
  }
}

Conclusion

Deploying Kutt on Rocky Linux 9.4 involves several steps, but with the correct configurations and troubleshooting, you can get it up and running smoothly. This guide should help you navigate through the process and resolve common issues related to SMTP, Docker, and environment configurations. Happy URL shortening!

App*Rocks

Search This Blog