Installation & Deployment

Install YeCha from scratch (core 1.2.5), then continue with the quick start.

On this page

Requirements

ItemRequirement
PHP8.1+ (8.3 recommended) with pdo_mysql, mbstring, curl, simplexml, fileinfo, zip, openssl
DatabaseMySQL 5.7+ / MariaDB 10.3+, utf8mb4
Web serverNginx 1.20+ or Apache 2.4+ with rewrite support
Writableuploads/, var/cache/, var/home-static/
OptionalHTTPS, CDN, OPcache (see operations)

install/schema.sql builds the schema; {PREFIX} is replaced by DB_PREFIX from config.inc.php.

Steps

  1. Unpack a release into docroot so index.php, core/, themes/, plugins/ sit at the same level.
  2. Create the database:
CREATE DATABASE yecha DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'yecha'@'127.0.0.1' IDENTIFIED BY 'strong-password';
GRANT ALL ON yecha.* TO 'yecha'@'127.0.0.1';
FLUSH PRIVILEGES;
  1. Configure: copy config.inc.php.example to config.inc.php:
define('DB_HOST', '127.0.0.1');
define('DB_PORT', '3306');
define('DB_NAME', 'yecha');
define('DB_USER', 'yecha');
define('DB_PASS', 'CHANGE_ME');
define('DB_PREFIX', 'ye_');
define('SECRET', 'replace-with-random-64-hex');
define('TZ', 'Asia/Shanghai');
define('SITE_LANG', 'zh_CN');
define('DEBUG', false);
  1. Run the installer at the site root (creates tables and the admin user). With a manual schema, php tools/upgrade.php --component core applies pending migrations. /install/ reports "already installed" afterwards.
  2. Configure rewrites (below), then nginx -t && nginx -s reload.
  3. Harden (see hardening) and sign in at /admin/.

Web server

Nginx

server {
    listen 80;
    server_name example.com;
    root /www/wwwroot/yecha.org;
    index index.php;

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

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

    location ~ ^/(var|data|tools|tests|core|config\.inc\.php) { deny all; }
    location ~* \.(bak|orig|old|save|swp|tmp|sql|gz|log)$ { deny all; }
}

Do not deny install during setup; lock it afterwards. Without rewrites, the ?r=… fallback works via index.php.

Apache

<Directory "/www/wwwroot/yecha.org">
    AllowOverride All
    Require all granted
</Directory>

Rewrite non-file requests to index.php and deny direct access to core/, var/, config.inc.php.

Permissions

chown -R www:www /www/wwwroot/yecha.org
find /www/wwwroot/yecha.org -type d -exec chmod 755 {} \;
find /www/wwwroot/yecha.org -type f -exec chmod 644 {} \;
chmod 640 /www/wwwroot/yecha.org/config.inc.php
chmod -R 775 /www/wwwroot/yecha.org/uploads /www/wwwroot/yecha.org/var

Never commit config.inc.php (it holds SECRET and DB credentials) to version control.

HTTPS & CDN

  • Serve the whole site over HTTPS; keep site.url aligned with the real hostname. Behind a reverse proxy set fastcgi_param HTTPS on, otherwise admin sessions may bounce back to the login page.
  • When a CDN is in front, pass the real client IP to PHP (REMOTE_ADDR): statistics, rate limits and comment anti-spam depend on it.
  • Serve a complete certificate chain including intermediates.

Hardening

  1. Change the admin password immediately (Users).
  2. Remove or lock install/; confirm /core/…, /var/…, /config.inc.php return 403.
  3. Keep DEBUG=false; enable it only for local troubleshooting.
  4. Generate a random 64-char SECRET and back it up offline — rotating it invalidates encrypted keys (AI keys, etc.).
  5. Grant the DB user access to this database only; keep backups outside docroot.

Verify

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/admin/
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/sitemap.xml
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/feed
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/healthz

Home, admin, sitemap, feed and healthz must work; settings must save; uploads must succeed; direct access to /core/version.php must be denied.

Common errors

SymptomCauseFix
/install/ 403deny rule also blocks the installerexclude install during setup
500 Unknown column 'c.words'legacy schemaALTER TABLE ye_contents ADD COLUMN words INT UNSIGNED NOT NULL DEFAULT 0; then backfill CHAR_LENGTH(content)
Blank home / template missingtheme lacks views/layout.phpswitch to the default yecha theme or add the view
Admin OK, posts 404rewrite not activeapply the Nginx config and reload
Upload failsuploads/ not writablefix ownership per permissions
Login loopsHTTPS detection / cookie domaincheck fastcgi_param HTTPS on, site URL, clear cookies
DB connection failswrong constants or grantstest with mysql -h127.0.0.1 -uyecha -p yecha

See also FAQ and operations.