# Setup Guide - Planit AI Template

Complete installation and configuration guide for the Planit AI WordPress and Next.js template on Japanese VPS/rental servers.

## 📋 Table of Contents

1. [Prerequisites](#prerequisites)
2. [Server Setup](#server-setup)
3. [WordPress Installation](#wordpress-installation)
4. [Database Setup](#database-setup)
5. [Next.js Installation](#nextjs-installation)
6. [Integration Configuration](#integration-configuration)
7. [Testing](#testing)
8. [Deployment](#deployment)
9. [Troubleshooting](#troubleshooting)

---

## Prerequisites

### System Requirements

- **Node.js** 18.0 or higher
- **yarn** package manager (required for Next.js)
- **PHP** 7.4 or higher (8.0+ recommended)
- **MySQL** 5.7 or higher (or MariaDB 10.3+)
- **VPS or rental server** with SSH access
- **Domain name** (or temporary IP address)
- **Basic knowledge** of Linux command line

### Recommended Japanese VPS/Rental Server Providers

#### VPS Providers
- **Sakura VPS** (さくらのVPS) - [vps.sakura.ad.jp](https://vps.sakura.ad.jp/)
- **ConoHa VPS** (コノハVPS) - [conoha.jp](https://www.conoha.jp/)
- **AWS Lightsail (Japan)** - [aws.amazon.com/lightsail](https://aws.amazon.com/lightsail/)
- **Google Cloud Platform (Japan)** - [cloud.google.com](https://cloud.google.com/)
- **Vultr (Tokyo)** - [vultr.com](https://www.vultr.com/)

#### Rental Server Providers
- **Sakura Internet** (さくらのレンタルサーバ) - [sakura.ne.jp](https://www.sakura.ne.jp/)
- **Xserver** (エックスサーバー) - [xserver.ne.jp](https://www.xserver.ne.jp/)
- **ConoHa WING** (コノハWING) - [conoha.jp/wing](https://www.conoha.jp/wing/)
- **Lolipop** (ロリポップ) - [lolipop.jp](https://lolipop.jp/)

---

## Server Setup

### Step 1: Initial Server Configuration

#### For VPS (Fresh Server)

1. **SSH Access**
   ```bash
   ssh root@your-server-ip
   # or
   ssh your-username@your-server-ip
   ```

2. **Update System Packages**
   ```bash
   # Ubuntu/Debian
   sudo apt update && sudo apt upgrade -y
   
   # CentOS/RHEL
   sudo yum update -y
   
   # Amazon Linux
   sudo yum update -y
   ```

3. **Install Required Software**
   ```bash
   # Ubuntu/Debian
   sudo apt install -y nginx mysql-server php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-gd php-imagick
   
   # CentOS/RHEL
   sudo yum install -y nginx mysql-server php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-gd
   ```

4. **Install Node.js**
   ```bash
   # Using NodeSource
   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt install -y nodejs
   
   # Or using nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   source ~/.bashrc
   nvm install 20
   ```

#### For Rental Server (Managed Hosting)

1. **Access Control Panel**
   - Log into your hosting provider's control panel
   - Note: Common panels include cPanel, Plesk, or custom panels (Sakura, ConoHa, etc.)

2. **Verify PHP Version**
   - Check PHP version in control panel
   - Ensure PHP 7.4 or higher is available
   - Switch PHP version if needed

3. **Access SSH** (if available)
   - Some rental servers provide SSH access
   - Check your hosting provider's documentation

---

## WordPress Installation

### Method 1: Manual Installation via FTP/SFTP

#### Step 1.1: Download WordPress

```bash
# On local machine
cd ~/Downloads
wget https://wordpress.org/latest.tar.gz
tar -xzf latest.tar.gz
```

#### Step 1.2: Upload to Server

**Option A: Using FTP Client (FileZilla, Cyberduck)**

1. Connect to server via FTP/SFTP
2. Navigate to server root directory:
   - VPS: `/var/www/html` or `/usr/share/nginx/html`
   - Rental Server: Usually `public_html` or `www`
3. Upload all WordPress files
4. Ensure proper file permissions:
   ```bash
   # On server via SSH
   sudo chown -R www-data:www-data /var/www/html
   sudo chmod -R 755 /var/www/html
   ```

**Option B: Using SCP from Command Line**

```bash
# From local machine
scp -r wordpress/* your-username@your-server-ip:/var/www/html/
```

#### Step 1.3: Configure Web Server

**Nginx Configuration** (`/etc/nginx/sites-available/wordpress`)

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/html;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

Enable site:
```bash
sudo ln -s /etc/nginx/sites-available/wordpress /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

**Apache Configuration** (if using Apache)

```apache
<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/html
    
    <Directory /var/www/html>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

### Method 2: WP-CLI Installation

#### Step 2.1: Install WP-CLI

```bash
cd ~
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --info
```

#### Step 2.2: Download WordPress

```bash
cd /var/www/html
sudo wp core download --allow-root
```

#### Step 2.3: Create Configuration

```bash
sudo wp config create --dbname=your_database --dbuser=your_user --dbpass=your_password --dbhost=localhost --allow-root
```

#### Step 2.4: Install WordPress

```bash
sudo wp core install --url=your-domain.com --title="Your Site" --admin_user=admin --admin_password=secure_password --admin_email=your@email.com --allow-root
```

### Method 3: One-Click Installer (Rental Servers)

Many Japanese rental servers offer one-click WordPress installation:

#### Sakura Internet (さくらのレンタルサーバ)
1. Log into control panel
2. Navigate to "WordPress簡単インストール" (WordPress Easy Install)
3. Select domain and directory
4. Click install button
5. Follow on-screen instructions

#### ConoHa WING
1. Access control panel
2. Go to "アプリケーション" (Applications)
3. Select WordPress
4. Configure domain and database
5. Complete installation

#### Xserver
1. Log into control panel
2. Navigate to "WordPress簡単インストール"
3. Select domain
4. Complete installation wizard

**Note:** After one-click installation, you may need to:
- Update WordPress to latest version
- Install required plugins manually
- Configure file permissions

---

## Database Setup

### Method 1: MySQL Command Line

#### Step 1.1: Access MySQL

```bash
# Login as root
sudo mysql -u root -p

# Or with MySQL root user
mysql -u root -p
```

#### Step 1.2: Create Database and User

```sql
-- Create database
CREATE DATABASE planitai_wp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Create user
CREATE USER 'wp_user'@'localhost' IDENTIFIED BY 'strong_password_here';

-- Grant privileges
GRANT ALL PRIVILEGES ON planitai_wp.* TO 'wp_user'@'localhost';

-- Flush privileges
FLUSH PRIVILEGES;

-- Exit
EXIT;
```

#### Step 1.3: Verify Database

```bash
mysql -u wp_user -p planitai_wp
SHOW TABLES;
EXIT;
```

### Method 2: phpMyAdmin

#### Step 2.1: Access phpMyAdmin

1. **Install phpMyAdmin** (if not pre-installed)
   ```bash
   # Ubuntu/Debian
   sudo apt install phpmyadmin
   
   # Configure during installation
   # Select web server (nginx/apache)
   # Set root password
   ```

2. **Access phpMyAdmin**
   - URL: `http://your-server-ip/phpmyadmin`
   - Or: `https://your-domain.com/phpmyadmin`
   - Login with MySQL root credentials

#### Step 2.2: Create Database

1. Click "新規作成" (New) or "データベース" (Database)
2. Enter database name: `planitai_wp`
3. Select collation: `utf8mb4_unicode_ci`
4. Click "作成" (Create)

#### Step 2.3: Create User

1. Click "ユーザーアカウント" (User Accounts) tab
2. Click "アカウントを追加" (Add User Account)
3. Enter username: `wp_user`
4. Select host: `localhost`
5. Enter password
6. Under "データベースに対する権限" (Database privileges):
   - Select database: `planitai_wp`
   - Click "すべて選択" (Select All)
   - Click "実行" (Go)

### Method 3: Control Panel (Rental Servers)

#### Sakura Internet / ConoHa / Xserver

1. **Access Control Panel**
   - Log into your hosting control panel

2. **Create Database**
   - Navigate to "MySQLデータベース" (MySQL Database)
   - Click "データベース作成" (Create Database)
   - Enter database name: `planitai_wp`
   - Note the database name (usually prefixed with your account)

3. **Create Database User**
   - Click "ユーザー作成" (Create User)
   - Enter username and password
   - Note: Username is often prefixed with account name

4. **Link User to Database**
   - Select database and user
   - Grant all privileges
   - Save configuration

5. **Note Database Credentials**
   - Database host: Usually `localhost` or provided hostname
   - Database name: Full name with prefix
   - Username: Full username with prefix
   - Password: The one you set

### Method 4: MariaDB (Alternative)

```bash
# Install MariaDB
sudo apt install mariadb-server

# Secure installation
sudo mysql_secure_installation

# Create database (same as MySQL)
sudo mysql -u root -p
CREATE DATABASE planitai_wp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'wp_user'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON planitai_wp.* TO 'wp_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

---

## Import Template Data

### Step 1: Install Migration Plugin

1. **Via WordPress Admin**
   - Log into WordPress admin: `http://your-domain.com/wp-admin`
   - Go to **プラグイン > 新規追加** (Plugins > Add New)
   - Search: "All-in-One WP Migration"
   - Click **今すぐインストール** (Install Now)
   - Click **有効化** (Activate)

2. **Via WP-CLI**
   ```bash
   cd /var/www/html
   sudo wp plugin install all-in-one-wp-migration --activate --allow-root
   ```

### Step 2: Import Backup File

#### Method A: Via WordPress Admin

1. Go to **All-in-One WP Migration > Import**
2. Click **Import From > File**
3. Upload `wordpress/planitai-wp.wpress`
4. Wait for completion (may take several minutes)
5. **Important:** Do not close browser during import

#### Method B: Via WP-CLI (for large files)

1. **Upload file to server**
   ```bash
   # From local machine
   scp wordpress/planitai-wp.wpress your-username@your-server:/tmp/
   ```

2. **Import via WP-CLI**
   ```bash
   cd /var/www/html
   sudo wp ai1wm import /tmp/planitai-wp.wpress --allow-root
   ```

#### Method C: Direct File Upload (for large files)

1. **Increase PHP limits** in `php.ini`
   ```ini
   upload_max_filesize = 512M
   post_max_size = 512M
   memory_limit = 256M
   max_execution_time = 300
   ```

2. **Or install extension**
   - Install "All-in-One WP Migration Unlimited Extension"
   - Or use WP-CLI method above

### Step 3: Update Permalinks

1. Go to **設定 > パーマリンク設定** (Settings > Permalinks)
2. Click **変更を保存** (Save Changes) - do this **twice**
3. Or via WP-CLI:
   ```bash
   sudo wp rewrite flush --allow-root
   ```

### Step 4: Update Site URLs (If Domain Changed)

#### Method A: Via Plugin

1. Install "Better Search Replace" plugin
2. Go to **ツール > Better Search Replace** (Tools > Better Search Replace)
3. Search: `https://planitai-wp.smacon.info`
4. Replace: `https://your-domain.com`
5. Select all tables
6. Click **実行** (Run)

#### Method B: Via WP-CLI

```bash
cd /var/www/html
sudo wp search-replace 'https://planitai-wp.smacon.info' 'https://your-domain.com' --allow-root
sudo wp option update siteurl 'https://your-domain.com' --allow-root
sudo wp option update home 'https://your-domain.com' --allow-root
```

---

## Configure WordPress

### Step 1: Configure reCAPTCHA

1. **Get reCAPTCHA Keys**
   - Visit [Google reCAPTCHA Admin Console](https://www.google.com/recaptcha/admin)
   - Click **+ Create** to create a new site
   - Enter a label for your site
   - Select **reCAPTCHA v3** (invisible, runs in background)
   - Add your domain(s) to the allowed domains list
   - Click **Submit**
   - **Copy both the Site Key and Secret Key**

2. **Configure Contact Form 7**
   - In WordPress admin: **お問い合わせ > 統合** (Contact > Integration)
   - Find **reCAPTCHA** section
   - Enter **Site Key** and **Secret Key**
   - Click **変更を保存** (Save Changes)

3. **Verify Contact Form**
   - Go to **お問い合わせ > お問い合わせフォーム** (Contact > Contact Forms)
   - Note the form ID (should be 219, or check the actual ID)
   - Test form submission

### Step 2: Configure Email (SMTP)

1. **Install WP Mail SMTP**
   - Go to **プラグイン > 新規追加** (Plugins > Add New)
   - Search: "WP Mail SMTP"
   - Install and activate

2. **Configure SMTP**
   - Go to **WP Mail SMTP > 設定** (WP Mail SMTP > Settings)
   - Choose your email provider (Gmail, SendGrid, etc.)
   - Enter SMTP credentials
   - Test email delivery

---

## Next.js Installation

### Step 1: Install Dependencies

1. **Navigate to Next.js Directory**
   ```bash
   cd /path/to/nextjs
   # or
   cd ~/nextjs
   ```

2. **Install Dependencies**
   ```bash
   yarn install
   ```

### Step 2: Configure Environment Variables

1. **Copy Environment Template**
   ```bash
   cp env.example .env.local
   ```

2. **Edit Environment Variables**
   
   Open `.env.local` and update:
   
   ```env
   NEXT_PUBLIC_WP_API_BASE=https://your-wordpress-domain.com/api/wp/v2
   NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_recaptcha_site_key_here
   ```
   
   **Configuration Notes:**
   - Replace `your-wordpress-domain.com` with your actual WordPress domain
   - Use the **same Site Key** configured in WordPress Contact Form 7
   - Ensure URLs use `https://` protocol for production

### Step 3: Update API Configuration

1. **Check Contact Form ID**
   - Open `lib/api.ts`
   - Find `submitContactForm` function
   - Verify form ID matches WordPress (default: 219)
   - Update if different

### Step 4: Run Development Server

```bash
yarn dev
```

Access at: `http://localhost:3000`

---

## Integration Configuration

### Step 1: Verify WordPress API Connection

```bash
# Test API endpoint
curl https://your-wordpress-domain.com/api/wp/v2/posts?per_page=1
```

Expected response: JSON data with post information

### Step 2: Configure CORS (If Required)

If you encounter CORS errors:

1. **Install CORS Plugin** (WordPress)
   - Go to **プラグイン > 新規追加** (Plugins > Add New)
   - Search: "REST API - Filter Fields"
   - Install and activate

2. **Or configure in Nginx**
   ```nginx
   location /api/ {
       add_header Access-Control-Allow-Origin *;
       add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
       add_header Access-Control-Allow-Headers "Content-Type";
   }
   ```

### Step 3: Verify Contact Form Integration

1. Check form ID in WordPress
2. Update in `nextjs/lib/api.ts` if different
3. Test form submission

---

## Testing

### Verification Checklist

- [ ] WordPress installation accessible
- [ ] WordPress REST API returns valid JSON data
- [ ] Next.js development server starts without errors
- [ ] Homepage loads and displays correctly
- [ ] Blog posts fetched and displayed from WordPress
- [ ] News posts fetched and displayed from WordPress
- [ ] Individual blog/news detail pages render with full content
- [ ] Contact form submits successfully
- [ ] reCAPTCHA v3 working (invisible)
- [ ] Email notifications received after form submission
- [ ] Images and media files load correctly
- [ ] Responsive design functions properly on mobile devices

### Common Issues

**Issue: Next.js cannot connect to WordPress API**
- Verify `NEXT_PUBLIC_WP_API_BASE` is correctly set in `.env.local`
- Ensure WordPress REST API is enabled and accessible
- Check CORS configuration
- Test API endpoint directly in browser

**Issue: Contact form submission fails**
- Verify form ID in `lib/api.ts` matches WordPress form ID
- Ensure reCAPTCHA keys are correctly configured
- Verify domain is added to reCAPTCHA allowed domains
- Check browser console for JavaScript errors

**Issue: Images not loading**
- Verify WordPress uploads directory permissions (755 for folders, 644 for files)
- Check image URLs in WordPress API response
- Verify Next.js image configuration in `next.config.ts`
- Clear browser cache and WordPress cache

---

## Deployment

### WordPress Deployment

1. **Production Setup**
   - Ensure SSL certificate is installed (HTTPS)
   - Update all URLs to use HTTPS
   - Configure backups
   - Set up security plugins

2. **SSL Certificate** (Let's Encrypt)
   ```bash
   sudo apt install certbot python3-certbot-nginx
   sudo certbot --nginx -d your-domain.com
   ```

### Next.js Deployment

#### Option 1: Vercel (Recommended)

1. **Connect Repository**
   - Push code to GitHub/GitLab
   - Connect to Vercel

2. **Configure Environment Variables**
   - Add `NEXT_PUBLIC_WP_API_BASE`
   - Add `NEXT_PUBLIC_RECAPTCHA_SITE_KEY`

3. **Deploy**
   - Vercel auto-deploys on push

#### Option 2: VPS Server (PM2)

1. **Build Application**
   ```bash
   yarn build
   ```

2. **Install PM2**
   ```bash
   npm install -g pm2
   # or
   yarn global add pm2
   ```

3. **Start with PM2**
   ```bash
   pm2 start yarn --name "nextjs" -- start
   pm2 save
   pm2 startup
   ```

4. **Configure Nginx Reverse Proxy**
   ```nginx
   server {
       listen 80;
       server_name your-nextjs-domain.com;
       
       location / {
           proxy_pass http://localhost:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_cache_bypass $http_upgrade;
       }
   }
   ```

### Post-Deployment Checklist

- [ ] Update all URLs to production domain
- [ ] Verify HTTPS is working
- [ ] Test all functionality
- [ ] Configure domain DNS
- [ ] Set up monitoring
- [ ] Configure backups

---

## Troubleshooting

### WordPress Issues

**Import fails with file size error:**
- Install "All-in-One WP Migration Unlimited Extension"
- Or increase PHP limits in `php.ini`:
  ```ini
  upload_max_filesize = 512M
  post_max_size = 512M
  memory_limit = 256M
  max_execution_time = 300
  ```

**Images not loading:**
- Check file permissions (folders: 755, files: 644)
- Verify uploads directory exists
- Clear browser cache

**Database connection errors:**
- Verify database credentials in `wp-config.php`
- Check database user has correct privileges
- Ensure database server is running

### Next.js Issues

**Build errors:**
- Check TypeScript errors: `yarn lint`
- Verify all environment variables are set
- Check for missing dependencies
- Run `yarn install` to ensure all dependencies are installed

**API connection errors:**
- Verify WordPress API is accessible
- Check CORS configuration
- Verify environment variables

**Contact form errors:**
- Check browser console for errors
- Verify reCAPTCHA keys
- Check form ID matches WordPress

### Server Issues

**Permission errors:**
```bash
# Fix WordPress permissions
sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;
```

**Nginx/Apache errors:**
- Check error logs: `sudo tail -f /var/log/nginx/error.log`
- Verify configuration: `sudo nginx -t`
- Restart service: `sudo systemctl restart nginx`

---

## Next Steps

After successful setup:

1. **Content Management**
   - Add content via WordPress admin
   - Create blog posts and news articles
   - Upload media files

2. **Customization**
   - Customize theme colors/styling
   - Add custom pages
   - Configure additional plugins

3. **Maintenance**
   - Regular WordPress updates
   - Regular Next.js dependency updates
   - Monitor performance and security
   - Set up automated backups

---

## 📚 Additional Resources

- [WordPress Documentation](https://wordpress.org/documentation/)
- [Next.js Documentation](https://nextjs.org/docs)
- [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)
- [Contact Form 7 Documentation](https://contactform7.com/docs/)
- [WP-CLI Handbook](https://wp-cli.org/)
- [Nginx Documentation](https://nginx.org/en/docs/)
- [Let's Encrypt Documentation](https://letsencrypt.org/docs/)

---

**Last Updated:** November 2024