#Deployment Guide

Detailed XinAdmin production environment deployment tutorial and best practices

When you're ready to deploy your XinAdmin application to a production environment, there are important things to ensure your application runs as efficiently as possible. In this article, we'll introduce some good starting points to ensure your XinAdmin application is properly deployed.

#Server Requirements

Ensure your server meets XinAdmin's runtime environment and has the relevant extensions installed.

• PHP >= 8.2
• MySQL >= 5.7
• Redis >= 3.0
• Nginx, Apache, FrankenPHP, or other server software ready
• PHP extensions: Ctype, cURL, DOM, Fileinfo, Filter, Hash, Mbstring, OpenSSL, PCRE, PDO, Session, Tokenizer, XML

#Frontend Packaging

Before deploying to the server, you need to package the frontend resource files locally. Execute the following command to package:

npm run build
# or
pnpm run build

After packaging, the /public/assets resources and /public/index.html files will be generated. If you use Git to manage your project, you can add the packaged files to Git.

#Frontend Resources Separate Deployment

If you want to deploy frontend resource files to a separate website, you need to modify the frontend API request path first. Modify the VITE_BASE_URL value in the .env.production file to your backend address:

# /.env.production
# Change to your backend website address:
VITE_BASE_URL=https://example.com

Then repackage the frontend and transfer the generated /public/assets resources and /public/index.html files to another website.

#Backend Deployment

You can deploy XinAdmin as a normal website. Create a website directory on the server and pull the latest project files via Git. For online environments, you can choose not to upload the /web directory. After each frontend repackage, simply sync the /public/assets directory and /public/index.html files to the server.

You need to use Nginx, Apache, or other server software to run the site. Configure the site's root directory as the XinAdmin project directory, with the runtime directory set to /public. If there's no runtime directory configuration option, directly configure the root directory as /public.

If you deploy your application to a server running Nginx, you can use the following configuration file as a starting point for configuring your web server.

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;
 
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
 
    index index.html index.php index.htm default.php default.htm default.html;
 
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
 
    location ~ /\.(?!well-known).* {
        deny all;
    }
    
    include enable-php-80.conf; # PHP reference configuration
}

By default, all requests are handled by the frontend index.html. The frontend accesses backend APIs through /index.php. If you deploy frontend resources separately, you can use the following configuration to hide index.php:

# When deploying separately, you can directly proxy all requests to index.php
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

If you want to deploy as a single site and hide index.php, you can modify the frontend API request path to /api and then proxy all /api requests to /index.php:

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

#Optimization

XinAdmin supports all Laravel production environment optimizations, including configuration, events, routes, and views.

You can use the following command to generate cache with one click:

php artisan optimize

#FrankenPHP

XinAdmin provides out-of-the-box FrankenPHP deployment solutions. You can refer to the FrankenPHP documentation.