Frequently Asked Questions (FAQ)

Common questions and solutions for AstrNest installation, configuration, usage, and troubleshooting.

📋 Table of Contents

Installation & Configuration
Usage Questions
Deployment Issues
Development Questions
Troubleshooting
Performance Optimization
Security & Permissions

🛠️ Installation & Configuration

Q: What are the minimum system requirements?

A: Minimum requirements:

CPU: 2 cores
Memory: 4GB RAM
Storage: 10GB free space
Java: JDK 21 or higher
MySQL: 8.0 or higher
Node.js: 18.0 or higher

Recommended for production: 4+ cores, 8GB+ RAM, SSD storage.

Q: How do I install Java 21 on my system?

A: Installation methods vary by operating system:

Windows:

bash

# Download from Oracle or use package manager
choco install openjdk21  # Using Chocolatey

macOS:

bash

# Using Homebrew
brew install openjdk@21

Linux (Ubuntu/Debian):

bash

sudo apt update
sudo apt install openjdk-21-jdk

Q: MySQL connection fails, what should I check?

A: Common issues and solutions:

Service Status:

bash

sudo systemctl status mysql
sudo systemctl start mysql  # If not running

Connection Test:
bash
```
mysql -u root -p -e "SELECT 1;"
```
1

User Permissions:

sql

GRANT ALL PRIVILEGES ON astrnest.* TO 'astrnest_user'@'localhost';
FLUSH PRIVILEGES;

Firewall Settings:
bash
```
sudo ufw allow 3306  # Allow MySQL port
```
1

Q: How to configure multiple storage providers?

A: Edit application.properties:

properties

# Enable multiple storage providers
storage.providers=LOCAL,ALIYUN,TENCENT

# Local storage configuration
storage.local.path=/data/uploads
storage.local.enabled=true

# Aliyun OSS configuration
storage.aliyun.enabled=true
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

# Storage strategy (priority order)
storage.strategy=AUTO  # AUTO, LOCAL_FIRST, CLOUD_FIRST

💡 Usage Questions

Q: How to upload large files (>100MB)?

A: Use chunked upload feature:

Increase file size limit:

properties

# Backend configuration
spring.servlet.multipart.max-file-size=500MB
spring.servlet.multipart.max-request-size=500MB

# Frontend configuration
VITE_UPLOAD_MAX_SIZE=524288000  # 500MB in bytes

Enable chunked upload:

javascript

// Frontend chunked upload example
const uploadLargeFile = async (file) => {
  const chunkSize = 5 * 1024 * 1024; // 5MB chunks
  const totalChunks = Math.ceil(file.size / chunkSize);
  
  for (let i = 0; i < totalChunks; i++) {
    const chunk = file.slice(i * chunkSize, (i + 1) * chunkSize);
    await uploadChunk(chunk, i + 1, totalChunks);
  }
};

Q: How to generate different thumbnail sizes?

A: Configure thumbnail sizes in backend:

properties

# Thumbnail configuration
thumbnail.sizes=200x200,400x400,800x800
thumbnail.quality=80
thumbnail.format=JPEG

# Enable automatic thumbnail generation
thumbnail.auto-generate=true

API call to get specific thumbnail:

http

GET /api/files/{fileId}/thumbnail?width=200&height=200&quality=90

Q: How to implement user role management?

A: Use built-in role system:

java

// Example: Check user permissions
@PreAuthorize("hasRole('ADMIN') or hasRole('USER')")
public void someMethod() {
    // Method implementation
}

// User role hierarchy
// ADMIN > USER > VISITOR

🚀 Deployment Issues

Q: Docker container fails to start, how to debug?

A: Debug steps:

Check container logs:

bash

docker-compose logs backend
docker-compose logs frontend
docker-compose logs mysql

Check container status:

bash

docker-compose ps
docker logs <container_id>

Test database connection:

bash

docker exec -it astrnest-mysql mysql -u root -p

Check environment variables:
bash
```
docker exec -it astrnest-backend env
```
1

Q: How to set up SSL/HTTPS for production?

A: Multiple approaches:

Using Nginx reverse proxy:

nginx

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /api {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Using Spring Boot SSL:

properties

server.port=8443
server.ssl.key-store-type=PKCS12
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=your-password
server.ssl.key-alias=tomcat

Q: How to configure load balancing?

A: For high availability:

Database replication:

sql

-- Master database
-- Configure replication in my.cnf

-- Slave database
-- Point to master for replication

Application load balancing:

nginx

upstream backend_servers {
    server backend1:8080;
    server backend2:8080;
    server backend3:8080;
}

location /api {
    proxy_pass http://backend_servers;
}

Session management:

properties

# Use Redis for session storage
spring.session.store-type=redis

Q: Maven build fails with "Operation not permitted" permission error?

A: This is a common permission issue, usually occurring in the following situations:

Insufficient target directory permissions:

bash

# Check target directory permissions
ls -la target/classes/

# Solution: Delete and recreate target directory
rm -rf target
./mvnw clean compile

File locked by another process:

bash

# Check if other Java processes are running
ps aux | grep java

# Kill related processes
kill -9 <pid>

Running with sudo privileges (not recommended):

bash

# Temporary solution (security risk)
sudo chown -R $USER:$USER .
./mvnw spring-boot:run

Best practices:
- Avoid developing as root user
- Ensure project directory is owned by current user
- Regularly clean target directory

Q: What are the differences between pip, Maven, and npm package managers?

A: This is a common confusion for beginners. The main differences are:

Package Manager	Language Ecosystem	Main Purpose	Configuration File	Package Repository
pip	Python	Python package management	`requirements.txt` `pyproject.toml`	PyPI
Maven	Java	Java project build and dependency management	`pom.xml`	Maven Central
npm	JavaScript/Node.js	Node.js package management	`package.json`	npm Registry

Q: Detailed comparison of Maven (Java) and npm (Node.js) dependency management philosophies

A: Maven and npm represent two fundamentally different approaches to dependency management:

Core Philosophy

Maven (Java world): "Convention over configuration" - emphasizes consistency, sharing, and reusability. Dependencies are libraries needed during compilation.
npm (Node.js/frontend world): "Project isolation and self-containment" - emphasizes independence, determinism, and portability. Dependencies are modules needed during runtime.

Dependency Storage

Maven: Global unique local repository (~/.m2/repository). All projects share the same dependency copies.
npm: Project-specific node_modules. Each project has its own independent and complete set of dependencies.

Processing Approach

Maven: Dependencies are treated as "raw materials" for compilation and packaging. Ultimately, only your code and necessary dependencies are packaged into a standalone deployable artifact (like JAR, WAR files).
npm: Dependencies are treated as part of the project's runtime. The project must carry its node_modules to run.

Advantages

Maven:

Saves disk space (multiple projects share dependencies of the same version)
Efficient builds (dependencies only need to be compiled/verified once in the local repository)
Standardization beneficial for enterprise-level unified management

npm:

Projects are completely self-contained - copy the project folder to run
Perfect version isolation - Project A and Project B can use different versions of the same dependency without affecting each other

Disadvantages

Maven:

Risk of "dependency hell" - if Project A upgrades a dependency shared by Project B, it may accidentally break Project B
Slightly complex environment configuration - requires understanding and configuring local and remote repositories

npm:

Occupies significant disk space (each project has a complete dependency tree)
Slow dependency installation, especially when initializing projects in new environments

Comprehensive Comparison Table

Dimension	Maven (Java)	pip (Python)	npm (Node.js)
Core Philosophy	"Sharing & Reuse" (global local repository)	"Sharing & Reuse" (global site-packages)	"Isolation & Self-containment" (project-specific node_modules)
Dependency Storage	Global repository in user directory (`~/.m2/repository`)	Global package directory in system/user directory (e.g., `~/.local/lib/python3.x/site-packages/` or within virtual environment)	Project-specific directory (`./node_modules`)
Dependency Nature	Compile-time dependencies (.jar files are pre-compiled bytecode)	Runtime dependencies (.py files are source code or pre-compiled binary extensions)	Runtime dependencies (.js files are source code or pre-compiled binary extensions)
Environment Isolation	Not natively supported, relies on pom.xml version declarations, prone to conflicts	Virtual environments (venv, conda) are standard practice and strong requirement	Project isolation is default behavior, also has nvm for Node version management
Project Deliverable	Standalone artifact package (JAR/WAR, containing dependencies)	Usually requires carrying environment (code + dependency list requirements.txt + virtual environment)	Project folder (code + node_modules + package.json)

Detailed explanation:

pip (Python):
- Manages Python third-party libraries
- Installation: pip install package_name
- Virtual environments: venv, virtualenv
- Suitable for data science, web development, etc.
Maven (Java):
- Not just a package manager, but also a build tool
- Manages dependencies, compilation, testing, packaging
- Lifecycle management (clean, compile, test, package)
- Suitable for enterprise Java applications
npm (Node.js):
- Manages JavaScript libraries and tools
- Suitable for both frontend and backend
- Script execution: npm run dev
- Suitable for full-stack development

Usage recommendations:

Python projects → Use pip
Java projects → Use Maven or Gradle
Frontend/Node.js projects → Use npm or yarn

💻 Development Questions

Q: How to extend the storage provider system?

A: Implement custom storage provider:

java

@Component
public class CustomStorageProvider implements StorageProvider {
    
    @Override
    public String upload(File file, String filename) {
        // Custom upload logic
        return "custom://" + filename;
    }
    
    @Override
    public InputStream download(String filepath) {
        // Custom download logic
        return new FileInputStream(filepath);
    }
}

properties

storage.providers=LOCAL,CUSTOM
storage.custom.enabled=true

Q: How to add custom image processing?

A: Implement image processor:

java

@Component
public class CustomImageProcessor implements ImageProcessor {
    
    @Override
    public void process(File image) {
        // Custom image processing logic
        // Watermark, filters, compression, etc.
    }
}

Q: How to implement API rate limiting?

A: Use Spring Boot rate limiting:

java

@Configuration
public class RateLimitConfig {
    
    @Bean
    public MeterRegistry meterRegistry() {
        return new SimpleMeterRegistry();
    }
    
    @Bean
    public RateLimiter rateLimiter() {
        return RateLimiter.of("api", RateLimiterConfig.custom()
            .limitForPeriod(100)
            .limitRefreshPeriod(Duration.ofMinutes(1))
            .build());
    }
}

🔧 Troubleshooting

Q: Upload fails with "File size exceeds limit"

A: Check and adjust size limits:

Backend configuration:

properties

spring.servlet.multipart.max-file-size=100MB
spring.servlet.multipart.max-request-size=100MB

Nginx configuration (if used):
nginx
```
client_max_body_size 100M;
```
1

Frontend validation:

javascript

const maxSize = 100 * 1024 * 1024; // 100MB
if (file.size > maxSize) {
  throw new Error('File too large');
}

Q: Thumbnail generation fails

A: Common issues and solutions:

Check image format support:

properties

# Supported formats
image.supported-formats=JPEG,PNG,GIF,WEBP

Verify image processing library:

bash

# Check if ImageMagick is installed
convert --version

Check file permissions:

bash

ls -la /data/uploads/
chmod 755 /data/uploads/

Q: Spring Boot application fails to start, port 8080 is already in use?

A: This is a common Spring Boot application startup issue. When you see the following error:

***************************
APPLICATION FAILED TO START
***************************

Description:

Web server failed to start. Port 8080 was already in use.

Action:

Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.

Here is the complete solution:

🔍 Find the process occupying port 8080

Method 1: Using lsof command

bash

sudo lsof -i :8080

bash

lsof -i :8080

Method 2: Using netstat command

bash

sudo netstat -tulpn | grep :8080

Method 3: Using ss command (recommended)

bash

sudo ss -lptn 'sport = :8080'

🎯 Kill the process occupying the port

After finding the Process ID (PID), use the following commands to kill it:

Gentle method (recommended to try first)

bash

kill PID_number

Example: kill 1234

Force method (if the above doesn't work)

bash

kill -9 PID_number

Example: kill -9 1234

🚀 Quick one-step solution

Solution 1: Directly kill the process occupying port 8080

bash

sudo kill -9 $(sudo lsof -t -i:8080)

Solution 2: If the above doesn't work, execute step by step

bash

# 1. Find the process occupying port 8080
sudo lsof -i :8080

# 2. Note the PID, then kill it (assuming PID is 1234)
kill 1234

# 3. If regular kill doesn't work, force kill
kill -9 1234

💡 Prevention and alternative solutions

Change Spring Boot port If you don't want to kill the existing process, you can change your application port:

Temporary solution: Specify port in startup command

bash

mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=8081

Permanent solution: Add to application.properties

properties

server.port=8081

Check if it's your own other instance Sometimes it's a previously started application that didn't fully exit:

bash

# View all Java processes
ps aux | grep java

# If there are multiple Spring Boot processes, kill them all
pkill -f spring-boot

🛠️ Practical command summary

bash

# Combined command: Find and kill the process on port 8080
sudo lsof -i :8080 && echo "Found the above process, use kill PID to terminate"

# Or directly force kill
sudo fuser -k 8080/tcp

Recommended execution order:

First use lsof -i :8080 to see what process is occupying the port
If it's an important service, consider changing ports
If it's a zombie process or useless, use kill PID to terminate
If it doesn't respond, then use kill -9 PID

Q: Database performance issues

A: Optimization strategies:

Index optimization:

sql

-- Add indexes for frequently queried columns
CREATE INDEX idx_user_uploads ON uploads(user_id, created_at);
CREATE INDEX idx_file_type ON uploads(file_type);

Query optimization:

sql

-- Use EXPLAIN to analyze queries
EXPLAIN SELECT * FROM uploads WHERE user_id = 1;

Database configuration:

ini

# my.cnf optimization
innodb_buffer_pool_size = 1G
innodb_log_file_size = 256M
query_cache_size = 64M

⚡ Performance Optimization

Q: How to improve image loading speed?

A: Multiple optimization techniques:

CDN integration:

properties

# Configure CDN for static assets
cdn.enabled=true
cdn.domain=cdn.yourdomain.com

Browser caching:

nginx

location ~* \.(jpg|jpeg|png|gif|ico)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Image optimization:

properties

# Enable WebP conversion
image.auto-convert-webp=true
image.quality=80

Q: How to handle high concurrent uploads?

A: Scaling strategies:

Horizontal scaling:

yaml

# Docker Compose with multiple instances
backend:
  image: astrnest/backend:latest
  deploy:
    replicas: 3

Async processing:

java

@Async
public CompletableFuture<String> processUpload(File file) {
    // Async file processing
    return CompletableFuture.completedFuture(result);
}

Queue system:

properties

# Redis queue configuration
spring.redis.host=localhost
spring.redis.port=6379

🔒 Security & Permissions

Q: How to secure API endpoints?

A: Security best practices:

JWT configuration:

properties

# Strong JWT secret
jwt.secret=your-very-long-secret-key-here
jwt.expiration=86400000

CORS configuration:

java

@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        // Configure allowed origins, methods, headers
    }
}

Input validation:

java

@Validated
public class UploadRequest {
    @NotBlank
    @Size(max = 255)
    private String filename;
    
    @NotNull
    @Max(100 * 1024 * 1024) // 100MB
    private Long fileSize;
}

Q: How to implement two-factor authentication?

A: 2FA implementation:

java

@Service
public class TwoFactorService {
    
    public String generateSecretKey() {
        return new GoogleAuthenticator().createCredentials().getKey();
    }
    
    public boolean verifyCode(String secret, int code) {
        GoogleAuthenticator gAuth = new GoogleAuthenticator();
        return gAuth.authorize(secret, code);
    }
}

Q: How to audit user activities?

A: Implement audit logging:

java

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Upload {
    
    @CreatedBy
    private String createdBy;
    
    @CreatedDate
    private LocalDateTime createdDate;
    
    @LastModifiedBy
    private String lastModifiedBy;
    
    @LastModifiedDate
    private LocalDateTime lastModifiedDate;
}

📞 Getting Help

Community Support

GitHub Issues: Report bugs and request features
Discussion Forum: Technical discussions and Q&A
Stack Overflow: Use tag [astrnest] for questions

Professional Support

Email: support@astrnest.com
Documentation: Complete documentation available
Consulting: Custom development and optimization services

Contributing

Code Contributions: Follow contribution guidelines
Documentation: Help improve documentation
Testing: Report bugs and test new features

🔗 Related Links: Quick Start Guide | API Documentation | Project Introduction

Frequently Asked Questions (FAQ) ​

📋 Table of Contents ​

🛠️ Installation & Configuration ​

Q: What are the minimum system requirements? ​

Q: How do I install Java 21 on my system? ​

Q: MySQL connection fails, what should I check? ​

Q: How to configure multiple storage providers? ​

💡 Usage Questions ​

Q: How to upload large files (>100MB)? ​

Q: How to generate different thumbnail sizes? ​

Q: How to implement user role management? ​

🚀 Deployment Issues ​

Q: Docker container fails to start, how to debug? ​

Q: How to set up SSL/HTTPS for production? ​

Q: How to configure load balancing? ​

Q: Maven build fails with "Operation not permitted" permission error? ​

Q: What are the differences between pip, Maven, and npm package managers? ​

Q: Detailed comparison of Maven (Java) and npm (Node.js) dependency management philosophies ​

Core Philosophy ​

Dependency Storage ​

Processing Approach ​

Advantages ​

Disadvantages ​

Comprehensive Comparison Table ​

💻 Development Questions ​

Q: How to extend the storage provider system? ​

Q: How to add custom image processing? ​

Q: How to implement API rate limiting? ​

🔧 Troubleshooting ​

Q: Upload fails with "File size exceeds limit" ​

Q: Thumbnail generation fails ​

Q: Spring Boot application fails to start, port 8080 is already in use? ​

🔍 Find the process occupying port 8080 ​

🎯 Kill the process occupying the port ​

🚀 Quick one-step solution ​

💡 Prevention and alternative solutions ​

🛠️ Practical command summary ​

Q: Database performance issues ​

⚡ Performance Optimization ​

Q: How to improve image loading speed? ​

Q: How to handle high concurrent uploads? ​

🔒 Security & Permissions ​

Q: How to secure API endpoints? ​

Q: How to implement two-factor authentication? ​

Q: How to audit user activities? ​

📞 Getting Help ​

Community Support ​

Professional Support ​

Contributing ​

Frequently Asked Questions (FAQ)

📋 Table of Contents

🛠️ Installation & Configuration

Q: What are the minimum system requirements?

Q: How do I install Java 21 on my system?

Q: MySQL connection fails, what should I check?

Q: How to configure multiple storage providers?

💡 Usage Questions

Q: How to upload large files (>100MB)?

Q: How to generate different thumbnail sizes?

Q: How to implement user role management?

🚀 Deployment Issues

Q: Docker container fails to start, how to debug?

Q: How to set up SSL/HTTPS for production?

Q: How to configure load balancing?

Q: Maven build fails with "Operation not permitted" permission error?

Q: What are the differences between pip, Maven, and npm package managers?

Q: Detailed comparison of Maven (Java) and npm (Node.js) dependency management philosophies

Core Philosophy

Dependency Storage

Processing Approach

Advantages

Disadvantages

Comprehensive Comparison Table

💻 Development Questions

Q: How to extend the storage provider system?

Q: How to add custom image processing?

Q: How to implement API rate limiting?

🔧 Troubleshooting

Q: Upload fails with "File size exceeds limit"

Q: Thumbnail generation fails

Q: Spring Boot application fails to start, port 8080 is already in use?

🔍 Find the process occupying port 8080

🎯 Kill the process occupying the port

🚀 Quick one-step solution

💡 Prevention and alternative solutions

🛠️ Practical command summary

Q: Database performance issues

⚡ Performance Optimization

Q: How to improve image loading speed?

Q: How to handle high concurrent uploads?

🔒 Security & Permissions

Q: How to secure API endpoints?

Q: How to implement two-factor authentication?

Q: How to audit user activities?

📞 Getting Help

Community Support

Professional Support

Contributing