192 lines
3.8 KiB
Markdown
192 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
nvm install 22
|
|
nvm use 22
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
Expected Node.js version:
|
|
|
|
```text
|
|
v22.x.x
|
|
```
|
|
|
|
This repository includes a `.nvmrc` file, so later terminal sessions can use:
|
|
|
|
```bash
|
|
nvm use
|
|
```
|
|
|
|
### 3. Start PostgreSQL
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
sudo -u postgres psql
|
|
```
|
|
|
|
Inside the PostgreSQL shell:
|
|
|
|
```sql
|
|
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:
|
|
|
|
```bash
|
|
psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
|
|
```
|
|
|
|
Exit with:
|
|
|
|
```sql
|
|
\q
|
|
```
|
|
|
|
### 5. Environment variables
|
|
|
|
When the backend application is added, create a local `.env` file from the provided example file.
|
|
|
|
Expected baseline variables:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
.
|
|
├── apps
|
|
│ ├── backend
|
|
│ └── web
|
|
├── packages
|
|
│ └── shared
|
|
├── docs
|
|
├── README.md
|
|
└── AGENTS.md
|
|
```
|
|
|
|
## Development workflow
|
|
|
|
After the project code is added, the usual local workflow should be:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
|
|
```
|
|
|
|
List databases:
|
|
|
|
```sql
|
|
\l
|
|
```
|
|
|
|
List tables:
|
|
|
|
```sql
|
|
\dt
|
|
```
|
|
|
|
Describe a table:
|
|
|
|
```sql
|
|
\d table_name
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
Check whether PostgreSQL is running:
|
|
|
|
```bash
|
|
sudo systemctl status postgresql
|
|
```
|
|
|
|
Restart PostgreSQL:
|
|
|
|
```bash
|
|
sudo systemctl restart postgresql
|
|
```
|
|
|
|
Check the installed Node.js version:
|
|
|
|
```bash
|
|
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.
|