Quick Start Guide

This guide will help you get AstrNest up and running quickly. Follow these step-by-step instructions to set up your development environment and start using the platform.

🚀 Quick Experience

Want to try AstrNest immediately? Follow these simple steps to get started in just a few minutes:

bash

# Clone the project
cd astrnest

# Start backend service
cd backend && mvn spring-boot:run

# Start frontend service (in a new terminal)
cd frontend && npm run dev

Access Address: http://localhost:5173

Default Admin Account:

Username: admin
Password: chenxi123

💡 Tip: For detailed setup instructions and troubleshooting, continue reading the full guide below.

🚀 Prerequisites

System Requirements

Minimum Requirements

CPU: 2 cores or more
Memory: 4GB RAM
Storage: 10GB free space
OS: Windows 10/11, macOS 10.15+, or Ubuntu 18.04+

Recommended Requirements

CPU: 4 cores or more
Memory: 8GB RAM or more
Storage: 50GB free space (SSD preferred)
OS: Latest stable version of your operating system

Software Requirements

Backend Development

Java: JDK 21 or higher
Maven: 3.6 or higher
MySQL: 8.0 or higher
Redis: 7.0 or higher (optional, for caching)

Frontend Development

Node.js: 18.0 or higher
npm: 8.0 or higher (comes with Node.js)

Development Tools

Git: For version control
Docker: For containerized deployment (optional)
IDE: IntelliJ IDEA, VS Code, or your preferred editor

📥 Installation Steps

Method 1: One-click Setup (Recommended)

Step 1: Clone the Repository

bash

# Clone the project
git clone https://github.com/luminous-ChenXi/astrnest.git
cd astrnest

# Checkout the latest stable version
git checkout v1.0.0

Step 2: Initialize Database

bash

# Create database and user
mysql -u root -p -e "CREATE DATABASE astrnest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p -e "CREATE USER 'astrnest_user'@'localhost' IDENTIFIED BY 'secure_password';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON astrnest.* TO 'astrnest_user'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"

# Import initial schema
mysql -u astrnest_user -p astrnest < database/init.sql

Step 3: Configure Backend

bash

# Navigate to backend directory
cd backend

# Copy configuration template
cp src/main/resources/application-template.properties src/main/resources/application.properties

# Edit configuration (use your preferred editor)
nano src/main/resources/application.properties

Update the configuration file:

properties

# Database Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/astrnest
spring.datasource.username=astrnest_user
spring.datasource.password=secure_password

# Server Configuration
server.port=8080

# File Storage Configuration
storage.local.path=/data/uploads
storage.max-file-size=104857600

# Security Configuration
jwt.secret=your-secret-key-here
jwt.expiration=86400000

Step 4: Start Backend Server

bash

# Build and run the application
mvn clean spring-boot:run

# Or build and run as a jar
mvn clean package
java -jar target/astrnest-backend-1.0.0.jar

Backend should now be running at http://localhost:8080

Step 5: Configure Frontend

Open a new terminal and navigate to the frontend directory:

bash

cd frontend

# Install dependencies
npm install

# Copy environment template
cp .env.template .env

# Edit environment variables
nano .env

Update the environment file:

bash

# API Configuration
VITE_API_URL=http://localhost:8080
VITE_API_TIMEOUT=30000

# Application Configuration
VITE_APP_TITLE=AstrNest
VITE_APP_DESCRIPTION=Modern Image Hosting Platform
VITE_UPLOAD_MAX_SIZE=104857600

Step 6: Start Frontend Development Server

bash

# Start development server
npm run dev

Frontend should now be running at http://localhost:3000

Method 2: Docker Compose (Fastest)

Step 1: Clone and Prepare

bash

git clone https://github.com/luminous-ChenXi/astrnest.git
cd astrnest/docker

Step 2: Configure Environment

bash

# Copy environment template
cp .env.template .env

# Edit environment variables
nano .env

Update the environment file:

bash

# Database Configuration
MYSQL_ROOT_PASSWORD=root123
MYSQL_DATABASE=astrnest
MYSQL_USER=astrnest_user
MYSQL_PASSWORD=secure_password

# Application Configuration
BACKEND_PORT=8080
FRONTEND_PORT=3000

# Storage Configuration
UPLOAD_PATH=/data/uploads

Step 3: Start Services

bash

# Start all services
docker-compose up -d

# Check service status
docker-compose ps

Services should now be running:

Backend: http://localhost:8080
Frontend: http://localhost:3000
MySQL: localhost:3306
Redis: localhost:6379

🔧 Configuration Details

Database Configuration

MySQL Settings

sql

-- Recommended MySQL configuration
SET GLOBAL innodb_buffer_pool_size = 134217728; -- 128MB
SET GLOBAL max_connections = 200;
SET GLOBAL query_cache_size = 67108864; -- 64MB

Backend Database Configuration

properties

# application.properties
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost:3306/astrnest?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
spring.datasource.username=astrnest_user
spring.datasource.password=secure_password

# JPA Configuration
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect

Backend Storage Configuration

Local Storage

properties

# Local file system storage
storage.local.path=/data/uploads
storage.local.max-file-size=104857600
storage.local.allowed-types=image/jpeg,image/png,image/gif

Cloud Storage (Optional)

properties

# Alibaba Cloud OSS
storage.aliyun.enabled=false
storage.aliyun.endpoint=oss-cn-hangzhou.aliyuncs.com
storage.aliyun.access-key=your-access-key
storage.aliyun.secret-key=your-secret-key
storage.aliyun.bucket-name=your-bucket

# Tencent Cloud COS
storage.tencent.enabled=false
storage.tencent.region=ap-beijing
storage.tencent.secret-id=your-secret-id
storage.tencent.secret-key=your-secret-key
storage.tencent.bucket-name=your-bucket

Frontend Configuration

Environment Variables

bash

# API Configuration
VITE_API_URL=http://localhost:8080
VITE_API_TIMEOUT=30000

# Application Settings
VITE_APP_TITLE=AstrNest
VITE_APP_DESCRIPTION=Modern Image Hosting Platform
VITE_UPLOAD_MAX_SIZE=104857600
VITE_UPLOAD_CHUNK_SIZE=1048576

# Feature Flags
VITE_ENABLE_ANALYTICS=false
VITE_ENABLE_PWA=false

Build Configuration

javascript

// vite.config.js
export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  },
  build: {
    outDir: 'dist',
    sourcemap: false
  }
})

🧪 Testing Your Installation

Backend Health Check

bash

# Test backend API
curl http://localhost:8080/api/health

# Expected response
{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "version": "8.0.0"
      }
    }
  }
}

Frontend Health Check

Open your browser and navigate to http://localhost:3000. You should see the AstrNest login page.

Database Connection Test

bash

# Test database connection
mysql -u astrnest_user -p -e "SELECT version();" astrnest

# Test table creation
mysql -u astrnest_user -p -e "SHOW TABLES;" astrnest

Open http://localhost:3000 in your browser
Use the default admin credentials:
- Username: admin
- Password: chenxi123
Change the default password after first login

Security Notice: For security reasons, it's highly recommended to change the default administrator password immediately after first login. Detailed instructions are available in the FAQ section.

🐛 Troubleshooting Common Issues

Port Conflicts

If ports 8080 or 3000 are already in use:

bash

# Check what's using the ports
netstat -ano | findstr :8080
netstat -ano | findstr :3000

# Change backend port
# In application.properties:
server.port=8081

# Change frontend port
# In package.json, modify dev script:
"dev": "vite --port 3001"

Database Connection Issues

bash

# Check MySQL service status
sudo systemctl status mysql

# Start MySQL if not running
sudo systemctl start mysql

# Check if user has proper permissions
mysql -u root -p -e "SHOW GRANTS FOR 'astrnest_user'@'localhost';"

Frontend Build Issues

bash

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version
node --version
npm --version

Backend Build Issues

bash

# Clean Maven cache
mvn clean

# Update Maven dependencies
mvn dependency:purge-local-repository

# Check Java version
java -version
mvn --version

🚀 Next Steps

1. Explore the Admin Dashboard

Navigate to the admin section
Review system statistics
Configure storage providers
Set up user permissions

2. Test File Upload

Upload sample images
Test different file types
Verify thumbnail generation
Check storage locations

3. Configure Security

Change default passwords
Set up SSL certificates
Configure firewall rules
Enable security features

4. Set Up Monitoring

Configure application logs
Set up performance monitoring
Enable health checks
Configure alerting

📚 Additional Resources

Documentation

API Documentation - Complete API reference

Support

GitHub Issues - Report bugs and request features
Community Forum - Get help from the community
Email Support - Direct support for critical issues

Learning Resources

FAQ - Common questions and solutions

🎉 Congratulations! You've successfully set up AstrNest.

Next Steps:

Quick Start Guide ​

🚀 Quick Experience ​

🚀 Prerequisites ​

System Requirements ​

Minimum Requirements ​

Recommended Requirements ​

Software Requirements ​

Backend Development ​

Frontend Development ​

Development Tools ​

📥 Installation Steps ​

Method 1: One-click Setup (Recommended) ​

Step 1: Clone the Repository ​

Step 2: Initialize Database ​

Step 3: Configure Backend ​

Step 4: Start Backend Server ​

Step 5: Configure Frontend ​

Step 6: Start Frontend Development Server ​

Method 2: Docker Compose (Fastest) ​

Step 1: Clone and Prepare ​

Step 2: Configure Environment ​

Step 3: Start Services ​

🔧 Configuration Details ​

Database Configuration ​

MySQL Settings ​

Backend Database Configuration ​

Backend Storage Configuration ​

Local Storage ​

Cloud Storage (Optional) ​

Frontend Configuration ​

Environment Variables ​

Build Configuration ​

🧪 Testing Your Installation ​

Backend Health Check ​

Frontend Health Check ​

Database Connection Test ​

First Login ​

🐛 Troubleshooting Common Issues ​

Port Conflicts ​

Database Connection Issues ​

Frontend Build Issues ​

Backend Build Issues ​

🚀 Next Steps ​

1. Explore the Admin Dashboard ​

2. Test File Upload ​

3. Configure Security ​

4. Set Up Monitoring ​

📚 Additional Resources ​

Documentation ​

Support ​

Learning Resources ​

Quick Start Guide

🚀 Quick Experience

🚀 Prerequisites

System Requirements

Minimum Requirements

Recommended Requirements

Software Requirements

Backend Development

Frontend Development

Development Tools

📥 Installation Steps

Method 1: One-click Setup (Recommended)

Step 1: Clone the Repository

Step 2: Initialize Database

Step 3: Configure Backend

Step 4: Start Backend Server

Step 5: Configure Frontend

Step 6: Start Frontend Development Server

Method 2: Docker Compose (Fastest)

Step 1: Clone and Prepare

Step 2: Configure Environment

Step 3: Start Services

🔧 Configuration Details

Database Configuration

MySQL Settings

Backend Database Configuration

Backend Storage Configuration

Local Storage

Cloud Storage (Optional)

Frontend Configuration

Environment Variables

Build Configuration

🧪 Testing Your Installation

Backend Health Check

Frontend Health Check

Database Connection Test

First Login

🐛 Troubleshooting Common Issues

Port Conflicts

Database Connection Issues

Frontend Build Issues

Backend Build Issues

🚀 Next Steps

1. Explore the Admin Dashboard

2. Test File Upload

3. Configure Security

4. Set Up Monitoring

📚 Additional Resources

Documentation

Support

Learning Resources