rg_backend_academy/README.md

RG Backend Academy

Educational full-stack project for learning backend development with Node.js, React, and a local PostgreSQL database.

The repository is intentionally small at the moment. Use this document as the baseline environment guide before adding the backend, frontend, database schema, tests, and deployment notes.

Planned stack

• Node.js 22 LTS or newer
• npm, pnpm, or another package manager selected by the project
• React for the frontend application
• PostgreSQL running locally on Ubuntu
• Git for version control

Ubuntu environment setup

The commands below target Ubuntu or Ubuntu-based Linux distributions.

1. Install system dependencies

sudo apt update
sudo apt install -y curl ca-certificates gnupg git build-essential postgresql postgresql-contrib

2. Install Node.js 22 with nvm

Using nvm keeps the project Node.js version isolated from the system installation.

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Restart the terminal, then install and use Node.js 22:

nvm install 22
nvm use 22
node --version
npm --version

Expected Node.js version:

v22.x.x

This repository includes a .nvmrc file, so later terminal sessions can use:

nvm use

3. Start PostgreSQL

sudo systemctl enable --now postgresql
sudo systemctl status postgresql

4. Create a local development database

Use a dedicated application user instead of the default postgres superuser.

sudo -u postgres psql

Inside the PostgreSQL shell:

CREATE USER rg_academy WITH PASSWORD 'rg_academy';
CREATE DATABASE rg_academy_dev OWNER rg_academy;
GRANT ALL PRIVILEGES ON DATABASE rg_academy_dev TO rg_academy;
\q

Test the connection:

psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"

Exit with:

\q

5. Environment variables

When the backend application is added, create a local .env file from the provided example file.

Expected baseline variables:

DATABASE_URL="postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
NODE_ENV="development"

Do not commit .env files with secrets or local credentials.

Suggested repository structure

The exact structure may evolve, but this is the recommended starting point:

.
├── apps
│   ├── backend
│   └── web
├── packages
│   └── shared
├── docs
├── README.md
└── AGENTS.md

Development workflow

After the project code is added, the usual local workflow should be:

nvm use
npm install
npm run dev

Recommended scripts to add once the application exists:

• npm run dev - start local backend and frontend development servers.
• npm run test - run automated tests.
• npm run lint - run static checks.
• npm run format - format source files.
• npm run db:migrate - apply database migrations.
• npm run db:seed - seed local development data.

PostgreSQL quick reference

Open the project database:

psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"

List databases:

\l

List tables:

\dt

Describe a table:

\d table_name

Troubleshooting

Check whether PostgreSQL is running:

sudo systemctl status postgresql

Restart PostgreSQL:

sudo systemctl restart postgresql

Check the installed Node.js version:

node --version

If psql cannot connect, verify that PostgreSQL is listening locally and that the database URL matches the user, password, host, port, and database name.

Documentation rules

• Project documentation is written in English.
• Code comments are written in English.
• User-facing chat responses for this project should be in Czech unless the user asks otherwise.