Lua 5.4 Development Environment (Pure Edition) - CentOS Stream 9 AMI Administrator Guide

1. Quick Start Information

Install Information:

OS: CentOS Stream 9
Lua version: 5.4.4 (System Package)
LuaRocks version: 3.13.0 (Latest, Source Compiled)
Lua Install Directory: /usr/bin/lua (System-wide)
LuaRocks Install Directory: /usr/local/bin/luarocks
Pre-installed Libraries: luasocket, luasec, luafilesystem, lua-cjson

Connection Methods:

Access the instance via SSH using the ec2-user user.
Use sudo to run commands requiring root privileges.

Verify Installation:

Check Lua version: lua -v
Check LuaRocks version: luarocks --version

Test all pre-installed libraries:

lua -e "require('socket'); require('ssl'); require('lfs'); require('cjson'); print('System Ready')"

Firewall Configuration:

Please allow SSH port 22.
For security, it is recommended to limit SSH access to trusted IPs only.

Important Note:

This AMI includes a complete C compilation environment (Development Tools), allowing you to compile and install additional Lua rocks that require native extensions.

2. Overview

Welcome to the Easycloud Lua 5.4 Development Environment AMI. This image is based on CentOS Stream 9 and provides a production-ready Lua development stack with essential libraries pre-installed.

Core Features of this AMI:

Battery Included: Pre-installed with four essential libraries (luasocket, luasec, luafilesystem, lua-cjson), eliminating the need for manual compilation.
Ready to Compile: Complete C development toolchain (GCC, Make, headers) is pre-configured, allowing you to install any Lua rock that requires native compilation.
Zero Config: LuaRocks paths are automatically configured system-wide via /etc/profile.d/luarocks.sh, ensuring all users can immediately access installed libraries.
Latest Stable Versions: Lua 5.4.4 from CentOS repositories and LuaRocks 3.13.0 compiled from official sources.
CRB Repository Enabled: The CRB (CodeReady Builder) repository is pre-enabled, solving common dependency issues on CentOS Stream 9.

Why This AMI is Different:

Problem	Traditional Installation	This AMI
Missing Dependencies	`lua-devel` package not found (CRB disabled by default)	CRB repository pre-enabled
Library Installation	Manual compilation and dependency resolution	4 essential libraries pre-installed and tested
Path Configuration	Manual LUA_PATH and LUA_CPATH setup	Automatic environment configuration via /etc/profile.d
Development Tools	Must manually install GCC, Make, headers	Complete Development Tools group pre-installed

Target Scenarios:

Lua scripting and application development
Network programming with LuaSocket
Secure HTTPS communication with LuaSec
File system operations and JSON processing
Rapid prototyping and automation tasks

3. First Launch & Access

Step 1: Configure Security Group (Cloud Firewall)

In your cloud provider's console (e.g., AWS EC2), add inbound rules to the security group for this instance to allow:

TCP Port 22 (SSH): Required for server access (Mandatory).

Security Recommendation:

Restrict SSH access to your office IP address or VPN subnet only.
Avoid opening SSH to 0.0.0.0/0 (the entire internet) in production environments.

Step 2: Connect via SSH

Get your instance's public IP address from the cloud console.
Use your SSH client to connect:
```
ssh ec2-user@[Your_Public_IP]
```
If prompted about host authenticity, type yes to continue.

Step 3: Verify Installation

After logging in, run the following commands to verify the environment is ready:

Check Lua Version:

lua -v

Check LuaRocks Version:

luarocks --version

Expected output:

/usr/local/bin/luarocks 3.13.0
LuaRocks main command-line interface

Verify Pre-installed Libraries (Quick Test):

lua -e "require('socket'); require('ssl'); require('lfs'); require('cjson'); print('System Ready')"

Expected output: System Ready

Verify Pre-installed Libraries (Detailed Test):

lua -e "
    print('Testing Environment...');
    local socket = require('socket'); print('  [OK] socket: ' .. socket._VERSION);
    local ssl    = require('ssl');    print('  [OK] ssl:    ' .. ssl._VERSION);
    local lfs    = require('lfs');    print('  [OK] lfs:    ' .. lfs._VERSION);
    local cjson  = require('cjson');  print('  [OK] cjson:  ' .. cjson._VERSION);
    print('Environment is PERFECT!');
"

Expected output:

Testing Environment...
  [OK] socket: LuaSocket 3.0.0
  [OK] ssl:    1.3.2
  [OK] lfs:    LuaFileSystem 1.9.0
  [OK] cjson:  2.1.0.10
Environment is PERFECT!

4. AMI Detailed Configuration & Architecture

This AMI has been configured with a complete Lua development environment. All installations follow Linux best practices.

Installation Architecture:

/usr/bin/lua                              <- Lua interpreter (system package)
/usr/bin/luac                             <- Lua compiler (system package)
/usr/include/lua*.h                       <- Lua C headers (lua-devel package)
/usr/lib64/liblua-5.4.so                  <- Lua shared library (for C embedding)
/usr/lib64/lua/5.4/                       <- System-level native modules directory
/usr/share/lua/5.4/                       <- System-level Lua source modules directory

/usr/local/bin/luarocks                   <- LuaRocks package manager (compiled)
/usr/local/etc/luarocks/config-5.4.lua    <- LuaRocks configuration file
/usr/local/lib/luarocks/rocks-5.4/        <- Installed rocks metadata (Manifests)

/etc/profile.d/luarocks.sh                <- System-wide path configuration (auto-loaded)

4.1. Lua Interpreter Installation

Paths

Path	Type	Description
`/usr/bin/lua`	File	Lua interpreter executable
`/usr/bin/luac`	File	Lua compiler (bytecode generator)
`/usr/include/`	Directory	Lua C API headers (lua.h, lauxlib.h, lualib.h, etc.)
`/usr/lib64/liblua-5.4.so`	File	Lua shared library for C embedding
`/usr/lib64/lua/5.4/`	Directory	System-level directory for native (.so) modules
`/usr/share/lua/5.4/`	Directory	System-level directory for Lua (.lua) source modules

Configuration (How-To-Create)

The following steps were performed to install Lua 5.4.4:

# 1. Update system packages
sudo dnf update -y

# 2. Install Development Tools group
# This includes GCC, Make, autoconf, automake, and other essential build tools
sudo dnf groupinstall -y "Development Tools"

# 3. Enable CRB (CodeReady Builder) repository
# CRITICAL STEP: Without this, lua-devel package will not be found
# CRB contains development packages for CentOS Stream 9
sudo dnf config-manager --set-enabled crb
sudo dnf makecache

# 4. Install Lua 5.4 and development packages
# lua: Interpreter and compiler
# lua-devel: C headers and static libraries for embedding Lua or building extensions
# openssl-devel: Required for LuaSec (SSL/TLS library)
sudo dnf install -y lua lua-devel openssl-devel

# 5. Verify installation
lua -v
# Expected output: Lua 5.4.4  Copyright (C) 1994-2022 Lua.org, PUC-Rio

Why This Configuration

System Package: Using the system-provided Lua ensures stability and security updates via dnf.
Development Tools: The complete toolchain allows compilation of any Lua rock requiring native extensions.
CRB Repository: CentOS Stream 9 requires explicit enabling of the CRB repository to access -devel packages.
OpenSSL Development Headers: Required for compiling LuaSec, which provides HTTPS support.

4.2. LuaRocks Package Manager Installation

Paths

Path	Type	Description
`/usr/local/bin/luarocks`	File	LuaRocks package manager executable
`/usr/local/bin/luarocks-admin`	File	LuaRocks repository administration tool
`/usr/local/etc/luarocks/config-5.4.lua`	File	LuaRocks configuration file (modify for custom repositories or proxies)
`/usr/local/lib/luarocks/rocks-5.4/`	Directory	Installed rocks metadata and manifests
`/usr/local/share/lua/5.4/`	Directory	LuaRocks-installed Lua source modules
`/usr/local/lib/lua/5.4/`	Directory	LuaRocks-installed native (.so) modules

Configuration (How-To-Create)

The following steps were performed to install LuaRocks 3.13.0:

# 1. Download official LuaRocks source package
wget https://luarocks.org/releases/luarocks-3.13.0.tar.gz

# 2. Extract the archive
tar zxpf luarocks-3.13.0.tar.gz
cd luarocks-3.13.0

# 3. Configure the build
# The configure script automatically detects the system Lua installation
# It will use /usr/bin/lua and link against /usr/lib64/liblua-5.4.so
./configure

# 4. Compile the source code
make

# 5. Install system-wide (requires root privileges)
sudo make install

# 6. Verify installation
luarocks --version
# Expected output: /usr/local/bin/luarocks 3.13.0

# 7. Clean up temporary files (optional)
cd ~
rm -rf luarocks-3.13.0 luarocks-3.13.0.tar.gz

Why Compile from Source

Latest Version: LuaRocks 3.13.0 is newer than most repository versions and includes important bug fixes.
Auto-Detection: The configure script automatically finds system Lua and configures paths correctly.
Standard Installation: Installing to /usr/local/ follows Linux FHS (Filesystem Hierarchy Standard) conventions.

4.3. Pre-installed Libraries (The Batteries)

Library Overview

Library	Version	Purpose
luasocket	3.0.0	TCP/UDP networking, HTTP client, SMTP, FTP protocols
luasec	1.3.2	SSL/TLS encryption for secure HTTPS connections
luafilesystem	1.9.0	Cross-platform file system operations (directory iteration, attributes, etc.)
lua-cjson	2.1.0.10	High-performance JSON encoding/decoding with C acceleration

Configuration (How-To-Create)

The following steps were performed to install the four essential libraries:

# Install luasocket (TCP/UDP networking)
sudo luarocks install luasocket

# Install luasec (SSL/TLS encryption)
# Requires openssl-devel to be already installed
sudo luarocks install luasec

# Install luafilesystem (file system operations)
sudo luarocks install luafilesystem

# Install lua-cjson (high-performance JSON)
sudo luarocks install lua-cjson

Why These Four Libraries

These four libraries are considered the "Standard Batteries" for Lua development:

luasocket: Essential for any network programming. Provides HTTP client, TCP/UDP sockets, and common protocols.
luasec: Adds SSL/TLS support to luasocket, enabling secure HTTPS connections (critical for modern web APIs).
luafilesystem: Provides cross-platform file system operations that are not available in standard Lua.
lua-cjson: The fastest JSON library for Lua, with C acceleration. JSON is ubiquitous in modern APIs and configuration files.

Installation Verification

After installation, all libraries are immediately available to all users. Test with:

lua -e "
local socket = require('socket')
local ssl = require('ssl')
local lfs = require('lfs')
local cjson = require('cjson')
print('All libraries loaded successfully!')
"

4.4. System-wide Path Configuration

Path

/etc/profile.d/luarocks.sh

File Content

This file is automatically sourced for all users at login, setting the correct LUA_PATH and LUA_CPATH environment variables.

export LUA_PATH='/usr/local/share/lua/5.4/?.lua;/usr/local/share/lua/5.4/?/init.lua;/usr/share/lua/5.4/?.lua;/usr/share/lua/5.4/?/init.lua;./?.lua;./?/init.lua;/usr/local/lib/luarocks/rocks-5.4/?.lua;/usr/local/lib/luarocks/rocks-5.4/?/init.lua'
export LUA_CPATH='/usr/local/lib/lua/5.4/?.so;/usr/lib64/lua/5.4/?.so;./?.so;/usr/local/lib/lua/5.4/loadall.so'

Configuration (How-To-Create)

The following steps were performed to configure system-wide paths:

# 1. Generate path configuration using luarocks
# The 'luarocks path' command outputs shell commands to set LUA_PATH and LUA_CPATH
luarocks path > /etc/profile.d/luarocks.sh

# 2. Make the script executable
# Files in /etc/profile.d/ must be executable to be sourced at login
chmod +x /etc/profile.d/luarocks.sh

# 3. Apply changes to current session
source /etc/profile.d/luarocks.sh

# 4. Verify environment variables are set
echo $LUA_PATH
echo $LUA_CPATH

How This Works

/etc/profile.d/: All executable shell scripts in this directory are automatically sourced for all users during login (both interactive and non-interactive sessions).
LUA_PATH: Tells the Lua interpreter where to search for .lua source modules when you use require().
LUA_CPATH: Tells the Lua interpreter where to search for .so native (C) modules when you use require().
Zero Configuration: Users don't need to manually edit .bashrc or set environment variables. Everything works out of the box.

Troubleshooting Path Issues

If a user reports "module not found" errors:

# 1. Verify the environment variables are set
echo $LUA_PATH
echo $LUA_CPATH

# 2. If empty, re-source the configuration
source /etc/profile.d/luarocks.sh

# 3. If still empty, regenerate the file
sudo luarocks path > /etc/profile.d/luarocks.sh
sudo chmod +x /etc/profile.d/luarocks.sh

5. Service Management (Quick Reference)

Lua is an interpreter, not a service. Here are the key commands:

Basic Lua Commands:

Start Lua REPL: lua
Run a script: lua script.lua
Run a one-liner: lua -e 'print("Hello, World!")'
Check version: lua -v
Compile to bytecode: luac script.lua (generates luac.out)
Exit REPL: Ctrl+D or os.exit()

LuaRocks Commands:

Search for a rock: luarocks search <name>
Install a rock: sudo luarocks install <name>
List installed rocks: luarocks list
Show rock information: luarocks show <name>
Remove a rock: sudo luarocks remove <name>
Update LuaRocks itself: sudo luarocks install luarocks

Development Workflow:

# 1. Create a Lua script
nano my_script.lua

# 2. Run the script
lua my_script.lua

# 3. If you need additional libraries
sudo luarocks install <library_name>

# 4. Run again
lua my_script.lua

6. Important File Locations

File Path	Purpose
`/usr/bin/lua`	Lua interpreter executable
`/usr/bin/luac`	Lua compiler (bytecode generator)
`/usr/include/lua*.h`	Lua C API headers (for embedding or extension development)
`/usr/lib64/liblua-5.4.so`	Lua shared library (for C embedding)
`/usr/lib64/lua/5.4/`	System-level native modules directory
`/usr/share/lua/5.4/`	System-level Lua source modules directory
`/usr/local/bin/luarocks`	LuaRocks package manager
`/usr/local/etc/luarocks/config-5.4.lua`	LuaRocks configuration file
`/usr/local/lib/luarocks/rocks-5.4/`	Installed rocks metadata
`/usr/local/share/lua/5.4/`	LuaRocks-installed Lua modules
`/usr/local/lib/lua/5.4/`	LuaRocks-installed native modules
`/etc/profile.d/luarocks.sh`	System-wide LUA_PATH and LUA_CPATH configuration

7. Troubleshooting

Problem: Module not found

Symptom: Running lua -e "require('socket')" returns:

lua: (command line):1: module 'socket' not found:

Possible Causes:

Environment variables not loaded: The /etc/profile.d/luarocks.sh file was not sourced.
```
source /etc/profile.d/luarocks.sh
lua -e "require('socket'); print('OK')"
```

Configuration file missing or corrupted:

cat /etc/profile.d/luarocks.sh

If missing or empty, regenerate it:

sudo luarocks path > /etc/profile.d/luarocks.sh
sudo chmod +x /etc/profile.d/luarocks.sh
source /etc/profile.d/luarocks.sh

Library not actually installed:

luarocks list | grep socket

If missing, reinstall:

sudo luarocks install luasocket

Problem: Permission denied when installing rocks

Symptom: Running luarocks install <name> returns "Permission denied".

Cause: LuaRocks tries to install system-wide by default, which requires root privileges.

Solution: Use sudo:

sudo luarocks install <library_name>

Alternative: Install to user directory (no sudo required):

luarocks install --local <library_name>

Note: This requires setting up local LUA_PATH and LUA_CPATH in your ~/.bashrc.

Problem: Compilation errors when installing rocks

Symptom: Installing a rock fails with errors like "gcc: command not found" or "lua.h: No such file or directory".

Cause: Development tools or Lua headers are missing.

Solution: Verify Development Tools and lua-devel are installed:

# Check if gcc is available
gcc --version

# Check if Lua headers are available
ls -l /usr/include/lua.h

# If missing, reinstall
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y lua-devel

Problem: LuaSec installation fails

Symptom: sudo luarocks install luasec fails with "openssl/ssl.h: No such file or directory".

Cause: OpenSSL development headers are missing.

Solution:

sudo dnf install -y openssl-devel
sudo luarocks install luasec

Problem: CRB repository warnings

Symptom: dnf commands show warnings about CRB repository.

Cause: This is normal. The CRB repository is less stable than the main repositories.

Solution: No action required. The warnings can be safely ignored.

Problem: Lua script runs slowly

Symptom: Lua script performance is poor.

Possible Causes and Solutions:

Using interpreted mode: Compile frequently-used modules to bytecode:
```
luac -o module.luac module.lua
```
Inefficient JSON library: Verify you're using lua-cjson (C-accelerated), not pure Lua JSON:
```
lua -e "local cjson = require('cjson'); print(cjson._VERSION)"
```
Consider LuaJIT: For CPU-intensive tasks, consider installing LuaJIT (Just-In-Time compiler):
```
sudo dnf install -y luajit luajit-devel
```

8. Advanced Topics

8.1. Example: Complete Working Script

Here's a real-world example demonstrating all pre-installed libraries:

Create the script:

cat > hello_env.lua <<'EOF'
-- Lua 5.4 Development Environment Demo Script
-- This script demonstrates all pre-installed libraries

local cjson = require("cjson")
local lfs = require("lfs")
local socket = require("socket")

-- Get current working directory
local current_dir = lfs.currentdir()

-- Build a status object
local status = {
    app = "Lua 5.4 Development Environment",
    message = "Hello World! All systems go.",
    timestamp = os.date("%Y-%m-%d %H:%M:%S"),
    environment = {
        lua_ver = _VERSION,
        os = "CentOS Stream 9",
        path = current_dir
    },
    modules = {
        cjson = cjson._VERSION,
        luafilesystem = lfs._VERSION,
        luasocket = socket._VERSION
    }
}

-- Encode to JSON and print
print("--------------------------------------------------")
print("JSON Output Generated:")
print(cjson.encode(status))
print("--------------------------------------------------")
EOF

Run the script:

lua hello_env.lua

Expected output:

--------------------------------------------------
JSON Output Generated:
{"app":"Lua 5.4 Development Environment","message":"Hello World! All systems go.","environment":{"path":"/home/ec2-user","os":"CentOS Stream 9","lua_ver":"Lua 5.4"},"modules":{"luafilesystem":"LuaFileSystem 1.9.0","luasocket":"LuaSocket 3.0.0","cjson":"2.1.0.10"},"timestamp":"2026-02-08 03:19:29"}
--------------------------------------------------

8.2. Making HTTPS Requests

Example of using luasocket + luasec for secure API calls:

local https = require("ssl.https")
local ltn12 = require("ltn12")

-- Perform HTTPS GET request
local response_body = {}
local res, code, response_headers, status = https.request{
    url = "https://api.github.com/users/lua",
    sink = ltn12.sink.table(response_body)
}

if code == 200 then
    print("Response:", table.concat(response_body))
else
    print("Error:", code, status)
end

8.3. File System Operations

Example of directory traversal:

local lfs = require("lfs")

print("Listing current directory:")
for file in lfs.dir(".") do
    if file ~= "." and file ~= ".." then
        local attr = lfs.attributes(file)
        print(string.format("%-30s %10d bytes  %s",
            file, attr.size, attr.mode))
    end
end

8.4. Installing Additional Rocks

To find and install more libraries:

# Search for a library
luarocks search redis

# Install a specific rock
sudo luarocks install lua-resty-redis

# Verify installation
lua -e "require('resty.redis'); print('OK')"

8.5. Embedding Lua in C Programs

The lua-devel package provides everything needed to embed Lua in C applications:

#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int main(void) {
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);

    luaL_dostring(L, "print('Hello from embedded Lua!')");

    lua_close(L);
    return 0;
}

Compile:

gcc -o embed embed.c -llua -lm -ldl
./embed

8.6. Creating Your Own Rock

Structure for a simple rock:

my-rock-1.0-1/
├── my-rock-1.0-1.rockspec  (metadata)
├── src/
│   └── my_module.lua       (your code)
└── README.md

Example rockspec:

package = "my-rock"
version = "1.0-1"
source = {
   url = "git://github.com/username/my-rock"
}
description = {
   summary = "My awesome Lua library",
   license = "MIT"
}
dependencies = {
   "lua >= 5.4"
}
build = {
   type = "builtin",
   modules = {
      my_module = "src/my_module.lua"
   }
}

Install locally:

sudo luarocks make my-rock-1.0-1.rockspec

9. Final Notes

This AMI provides a complete, production-ready Lua development environment with the following key benefits:

Key Takeaways:

Battery Included: Four essential libraries (luasocket, luasec, luafilesystem, lua-cjson) are pre-installed and ready to use.
Ready to Compile: Complete Development Tools group and lua-devel package allow installation of any rock requiring native compilation.
Zero Config: System-wide path configuration ensures all users can immediately start developing without manual setup.
Latest Stable Versions: Lua 5.4.4 from system repositories and LuaRocks 3.13.0 compiled from official sources.
CRB Repository Pre-enabled: Solves the common "lua-devel not found" issue on CentOS Stream 9.

Recommended Next Steps:

Explore the example script (hello_env.lua) to understand all pre-installed libraries.
Read the official Lua documentation: https://www.lua.org/manual/5.4/
Browse available rocks: https://luarocks.org/
Consider installing additional libraries for your specific use case (databases, web frameworks, etc.).

For support or questions, please contact the Easycloud team.

1. Quick Start Information​

2. Overview​

3. First Launch & Access​

Step 1: Configure Security Group (Cloud Firewall)​

Step 2: Connect via SSH​

Step 3: Verify Installation​

4. AMI Detailed Configuration & Architecture​

4.1. Lua Interpreter Installation​

Paths​

Configuration (How-To-Create)​

Why This Configuration​

4.2. LuaRocks Package Manager Installation​

Paths​

Configuration (How-To-Create)​

Why Compile from Source​

4.3. Pre-installed Libraries (The Batteries)​

Library Overview​

Configuration (How-To-Create)​

Why These Four Libraries​

Installation Verification​

4.4. System-wide Path Configuration​

Path​

File Content​

Configuration (How-To-Create)​

How This Works​

Troubleshooting Path Issues​

5. Service Management (Quick Reference)​

6. Important File Locations​

7. Troubleshooting​

Problem: Module not found​

Problem: Permission denied when installing rocks​

Problem: Compilation errors when installing rocks​

Problem: LuaSec installation fails​

Problem: CRB repository warnings​

Problem: Lua script runs slowly​

8. Advanced Topics​

8.1. Example: Complete Working Script​

8.2. Making HTTPS Requests​

8.3. File System Operations​

8.4. Installing Additional Rocks​

8.5. Embedding Lua in C Programs​

8.6. Creating Your Own Rock​

9. Final Notes​

1. Quick Start Information

2. Overview

3. First Launch & Access

Step 1: Configure Security Group (Cloud Firewall)

Step 2: Connect via SSH

Step 3: Verify Installation

4. AMI Detailed Configuration & Architecture

4.1. Lua Interpreter Installation

Paths

Configuration (How-To-Create)

Why This Configuration

4.2. LuaRocks Package Manager Installation

Paths

Configuration (How-To-Create)

Why Compile from Source

4.3. Pre-installed Libraries (The Batteries)

Library Overview

Configuration (How-To-Create)

Why These Four Libraries

Installation Verification

4.4. System-wide Path Configuration

Path

File Content

Configuration (How-To-Create)

How This Works

Troubleshooting Path Issues

5. Service Management (Quick Reference)

6. Important File Locations

7. Troubleshooting

Problem: Module not found

Problem: Permission denied when installing rocks

Problem: Compilation errors when installing rocks

Problem: LuaSec installation fails

Problem: CRB repository warnings

Problem: Lua script runs slowly

8. Advanced Topics

8.1. Example: Complete Working Script

8.2. Making HTTPS Requests

8.3. File System Operations

8.4. Installing Additional Rocks

8.5. Embedding Lua in C Programs

8.6. Creating Your Own Rock

9. Final Notes