AstrNest Installation and Configuration Guide

This guide is designed for DevOps engineers and developers who are setting up the AstrNest project for the first time. It lists all required manual parameters and specifies the file paths that need to be modified. After completing all items in this guide, you can start Docker Compose or local processes to get accessible /upload/{yyyy}/{MM}/... image direct links with 20MB upload limits.

1. Quick Checklist

Item	Required Content	File/Location to Modify
Database Connection	Host, Port, Database Name, Username, Password	.env / backend/src/main/resources/application.yml / docker-compose.yml (mysql, backend service environment variables) / backend/db/init.sql
Administrator Account	Username, Initial Password, Display Name, Email	.env + backend/db/init.sql (INSERT INTO users ...)
Upload Path	Local Disk Directory, External Access Prefix	.env (ASTRNEST_STORAGE_ROOT/ASTRNEST_STORAGE_PUBLIC), configure Nginx reverse proxy for /upload/** to backend if needed
Site Domain	Frontend Site URL, Image Direct Link Domain, API Domain	.env (PUBLIC_SITE_URL/PUBLIC_ASSET_URL/BACKEND_API_PUBLIC_URL), asset_domain in backend "System Configuration"
Backend Address	API Address Accessed by Frontend	frontend/.env or compile-time VITE_API_BASE_URL
Image Access URL	Default https://{current-domain}/upload/{yyyy}/{MM}/file when asset_domain not configured	Nginx/gateway /upload/** reverse proxy to backend:8080, or specify domain in .env for ASTRNEST_ASSET_DOMAIN/VITE_PUBLIC_ASSET_BASE
Email Service	SMTP Host/Port/Username/Password/Sender	Configure in backend "Settings > Email Service" after startup, or modify placeholder values in backend/db/init.sql chenxi_mail_config section

1.1 File Path Quick Reference

File Path	Parameters to Confirm/Modify	Usage Scenario
.env (root directory)	MYSQL_*, ASTRNEST_DB_*, ASTRNEST_STORAGE_*, ASTRNEST_ADMIN_*, PUBLIC_SITE_URL, PUBLIC_ASSET_URL, BACKEND_API_PUBLIC_URL, ASTRNEST_ASSET_DOMAIN, VITE_API_BASE_URL, VITE_PUBLIC_ASSET_BASE, VITE_SITE_NAME, SMTP_*	Unified entry for Docker Compose and local shell, docker compose --env-file .env up -d reads these values
docker-compose.yml	services.mysql.environment.* (database name/username/password), services.backend.environment.* (backend connection string, admin, storage path), services.frontend.environment.* (frontend access to backend/image URLs)	Override .env values directly in service environment blocks if needed for specific environments
backend/src/main/resources/application.yml	spring.datasource.*, astrnest.storage.*, astrnest.admin.*	Fallback configuration for bare-metal deployment or IDE debugging, all keys can be overridden by environment variables
backend/db/init.sql	CREATE DATABASE/USER, GRANT, INSERT INTO users, INSERT INTO chenxi_mail_config, UPDATE system_config	Initialize database structure, admin information, and SMTP placeholders; replace database name/username, admin email, and password hash before deployment
frontend/.env.development / .env.production / .env.example	VITE_API_BASE_URL, VITE_PUBLIC_ASSET_BASE, VITE_SITE_NAME	Control which backend the frontend connects to and the domain/path for generating image direct links
frontend/src/services/http.js	axios.create({ baseURL: ... })	Directly hardcode backend request address here if not relying on .env

📦 Recommended Approach: First copy .env.example to .env, ensure all items match the target environment, then adjust application.yml, init.sql, and frontend/.env.production accordingly.

2. Environment Variables Example (.env)

cp .env.example .env
# Edit .env to take effect in docker compose / shell

.env is read by docker-compose.yml, backend/src/main/resources/application.yml, and frontend build scripts. Make sure to replace all placeholder values before starting:

• First configure database host, port, database name, username, and password correctly, ensuring MYSQL_* and ASTRNEST_DB_* point to the same instance;
• Then set administrator username/password/email so the initialization script creates the correct super administrator;
• Write site domain, image access domain, and backend public address according to deployment topology, and configure /upload/** mapping in Nginx or load balancer layer;
• Prepare SMTP host, port, and authorization code in advance if email functionality is needed;
• Finally adjust VITE_API_BASE_URL for frontend backend access and VITE_PUBLIC_ASSET_BASE for image direct links to public domain names.

Key Variables:

• MYSQL_ROOT_PASSWORD / MYSQL_DATABASE / MYSQL_USER / MYSQL_PASSWORD: Database name and account password required for mysql container initialization, also convenient for DBAs to copy to existing MySQL hosts.
• ASTRNEST_DB_URL / ASTRNEST_DB_USERNAME / ASTRNEST_DB_PASSWORD: Backend JDBC connection string, username, password; in Docker mode can write directly as jdbc:mysql://mysql:3306/${MYSQL_DATABASE}?..., change to real host for bare-metal deployment.
• ASTRNEST_STORAGE_ROOT: Real directory mapped in container/host machine, example ./storage/upload:/storage/upload. System automatically creates YYYY/MM subdirectories under this directory.
• ASTRNEST_STORAGE_PUBLIC: External path prefix, defaults to /upload, so direct links are https://site/upload/{yyyy}/{MM}/{filename}.
• ASTRNEST_ASSET_DOMAIN + PUBLIC_SITE_URL / PUBLIC_ASSET_URL / BACKEND_API_PUBLIC_URL: If hosting assets on CDN, write actual domain here and add /upload/** reverse proxy in Nginx/Caddy; PUBLIC_SITE_URL used for concatenating site homepage in email scenarios.
• ASTRNEST_MULTIPART_MAX_FILE_SIZE / ASTRNEST_MULTIPART_MAX_REQUEST_SIZE: Must remain within 20MB, otherwise conflicts with database CHECK (size <= 20971520).
• ASTRNEST_ADMIN_*: Administrator information automatically stored in database on first startup; password stored as bcrypt before database storage.
• SMTP_HOST / SMTP_PORT / SMTP_USERNAME / SMTP_PASSWORD / SMTP_SECURE_TYPE / SMTP_FROM_*: Keep consistent with chenxi_mail_config placeholder values in init.sql for easy subsequent import.
• VITE_API_BASE_URL / VITE_PUBLIC_ASSET_BASE / VITE_SITE_NAME: Injected during frontend build, used for axios, copy direct link button, and browser tab title.

3. Backend Configuration (application.yml)

• Location: backend/src/main/resources/application.yml
• Already references above environment variables by default; if hardcoding is needed, can change to plain strings:

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/astrnest?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
    username: astrnest
    password: astrnestPass!
  servlet:
    multipart:
      max-file-size: 20MB
      max-request-size: 20MB

astrnest:
  storage:
    strategy: LOCAL
    local:
      root: /storage/upload
      public-base-url: /upload
  admin:
    username: admin
    password: chenxi123
    display-name: Super Administrator
    email: admin@example.com

Important: public-base-url can only use relative paths (starting with /upload), otherwise Spring's static resource mapping won't work; if using CDN domain, fill in asset_domain in backend "System Configuration".

4. Database Initialization (backend/db/init.sql)

• Coverage: Database creation, user accounts, all table structures, views, indexes, and default data.
• Required modifications:
  • Script top CREATE DATABASE section, synchronize modifications if changing database name or account password.
  • INSERT INTO users ... VALUES (1, 'admin', '<bcrypt>', ...): Can replace with self-generated bcrypt password, or keep default chenxi123.
  • INSERT INTO chenxi_mail_config ... VALUES (...): Write real SMTP host/account/authorization code, or keep default and modify later in backend.
• New capabilities:
  • upload_records automatically completes media_uuid, file_hash, width/height/duration, ai_description, thumbnail_url, view/download/report_count, metadata JSON fields, and includes CHECK (size <= 20971520); script also generates media / media_tags views and interactions behavior table.
  • tags + upload_record_tags add type/source/confidence/created_at for distinguishing user tags from AI tags.

Execution method:

mysql -u root -p < backend/db/init.sql

5. Frontend Environment Files

• Location: frontend/.env.development / frontend/.env.production (can create), or inject during build command line.
• Recommended content:

VITE_API_BASE_URL=https://api.astrnest.com
VITE_PUBLIC_ASSET_BASE=https://cdn.astrnest.com/upload
VITE_SITE_NAME=AstrNest

6. Upload and Static Resources

1. Directory Structure: LocalStorageHandler writes each file to ${ASTRNEST_STORAGE_ROOT}/{yyyy}/{MM}/filename.
2. Default Access: If asset_domain is empty, backend returns /upload/{yyyy}/{MM}/filename, browser accesses based on current domain.
3. Reverse Proxy: Need to add in Nginx/gateway layer:

location /upload/ {
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://127.0.0.1:8080/upload/;
}

4. CDN/Custom Domain: Fill in https://cdn.xxx.com in backend -> System Configuration, or write directly in database system_config.asset_domain; API will change image URL to https://cdn.xxx.com/upload/{...}.

7. Email Configuration

• After startup, log into backend and go to "Settings > Email Service", fill in SMTP host, port, authorization code, sender address.
• If wanting initialization script to write real values, replace placeholder strings in INSERT INTO chenxi_mail_config in backend/db/init.sql with production credentials (script disables this configuration by default).

8. Final Checklist

1. Whether .env, application.yml, frontend/.env* have all been replaced with real addresses/accounts.
2. Whether administrator email, SMTP, UPDATE upload_records in backend/db/init.sql all conform to reality.
3. (Optional) Use docker compose --env-file .env up -d to start once, access:
   • http://{server}:8080/actuator/health → UP
   • http://{server}/upload/{yyyy}/{MM}/demo.png → Returns 200 or 404 (depending on file existence, but cannot 502/302 redirect to homepage).

After completing above steps, proceed with "Quick Start / Docker Deployment" in README to start. Wishing you smooth usage 🛠️.