English | 简体中文

Admin Template

A admin template by Ruby. Related links:

• Blog post：如何做好一个软件项目
• Golang version: Admin Starter

Features

• Robust core functionality of the management system: includes basic authentication and authorization features, with a permission system based on the RBAC model, controlling access to all interfaces. The permission list is automatically generated by the backend routes, eliminating the need for manual maintenance. Comprehensive front-end and back-end multilingual support.
• Convenient development experience: all environments are containerized, enabling quick development with only Docker installed locally. Common commands are encapsulated using Makefile for ease of use.
• Reliable project management: comprehensive CI/CD functionality simplifies the build and deployment process. Code standards and unit tests are implemented to ensure project quality.
• Simplified deployment: production environment is encapsulated in a separate folder, easily uploaded to the server, configured, and started. Containerized deployment is versatile across server versions.

System Demonstration

URL: https://admin-template.hdgcs.com/ Credentials: root/4OGoH9w9S9VaVtVE0ZK1

The account is a super administrator, allowing you to log in and perform related functionality testing. Below is a demonstration of the testing steps:

1. Log in with the super administrator account.
2. Navigate to "System Management" -> "Role Management" -> "New". Enter the name as "Read-only Role", then select permissions for "UserList" and "RoleList". Click confirm to create.
3. Go to "System Management" -> "User Management" -> "New". Enter the name as "Read-only User", and enter the username and password as "readonly" and "000000" respectively. Assign the role created above, and click confirm to create.
4. Log in again with the created user credentials: "readonly", "000000". Navigate back to "Role Management" and "User Management". Notice that only the list display functionality is available, and the "New", "Edit", and "Delete" buttons are hidden. Attempting to bypass frontend elements and directly call backend APIs will result in a 403 Forbidden response.

System Usage

To use the system, you need to prepare a server with a minimum configuration of 1C2G, recommended 2C4G. Follow these specific steps:

1. Clone the code locally: git clone [email protected]:songhuangcn/admin-template.git
2. Install required dependencies on the server: Docker 20+, make.
3. Upload the deployment folder to your server: ssh your-host "mkdir -p /home/ubuntu/admin-template" && scp -r admin-template/deployment your-host:/home/ubuntu/admin-template/
4. Log in to the server and configure the system:
   • Configure environment variables: cp secrets/.env.sample secrets/.env, then modify the contents of secrets/.env. Configure your own values for APP_DOMAIN and SECRET_KEY_BASE, and adjust others as needed.
   • Configure SSL certificate: Upload your domain certificate to the server, location: secrets/ssl.crt and secrets/ssl.key.
5. On the GitLab platform (gitlab.com or other self-hosted platforms), create your project, go to "Settings" -> "CI/CD" -> "Variables", and configure the variables needed for deployment (only input Key and Value for variables, leave other configurations as default):
   • DEPLOY_SERVER: Keep it consistent with the APP_DOMAIN configured on your server.
   • SSH_PRIVATE_KEY: Text value of the SSH private key that can access your server. CI machine needs permission to deploy to your server.
   • DEPLOY_USERNAME: Credentials for your machine to access the CI-built image. Create in "Settings" -> "Repository" -> "Deploy tokens" and fill in the created token.
   • DEPLOY_TOKEN: Consistent with DEPLOY_USERNAME.
6. Push the code to the GitLab platform, and CI/CD will automatically perform image building and deployment.
7. For future feature additions or changes (refer to the subsequent "Local Development" documentation), submitting an MR will trigger build and verification. Merging the MR will result in automatic deployment.

CI/CD Explanation

The system utilizes GitLab CI/CD for building, testing, and deployment. The pipeline consists of three stages:

1. build: Builds the dev image for the current code version, used for subsequent testing and verification. If the pipeline is triggered on the main branch, it additionally builds the prod image for later deployment. Images for both front-end and back-end are only built when there are code changes.

2. test: Runs tests using the environment images built in the previous stage to ensure the health of the new code. Testing for both front-end and back-end is performed only when there are code changes.

3. deploy: Deploys the successfully built images from the "build" stage that have passed the test verification. This stage only runs on the main branch.

Local Development

1. Install Dependencies

All dependencies are resolved using Docker, so you only need to install Docker 20+. The tech stack includes Ruby 3, Rails 7, Vue.js 3, and MySQL 8.

brew install --cask docker # Should work for Docker 20 and above

2. Install the System

Please use the provided script for installation, which includes Docker initialization, bundle install, pnpm install, and database initialization steps.

make setup
make up

Once the system is running, you can access the services through the following links:

• Frontend: http://localhost:4000
• Backend: http://localhost:3000
• Database: mysql://root:password@localhost:3306

3. Management the System

The project utilizes a Makefile to encapsulate common commands, directing them to the appropriate container. For example, the command make console is actually interpreted as docker compose -f docker-compose.dev.yml run --rm rails bundle exec rails console.

This encapsulation shortens long commands and aims to provide an experience close to native development.

make up/upd/down    # Start/Start in the background/Stop the application
make restart        # Restart in the background, used when updating package dependencies
make bash-rails     # Enter the Rails container's bash
make build          # Rebuild front-end and back-end images
make package        # Execute front-end and back-end package install tasks, e.g., `bundle install`, `pnpm install`
make console        # Enter the Rails Console console

4. Configure the System

1. Development Environment: Makefile, docker-compose.dev.yml, backend/Dockerfile:dev, frontend/Dockerfile:dev
2. Deployment Environment: deployment/Makefile, deployment/docker-compose.prod.yml, backend/Dockerfile:prod, frontend/Dockerfile:prod