Skip to main content

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:

ProblemTraditional InstallationThis AMI
Missing Dependencieslua-devel package not found (CRB disabled by default)CRB repository pre-enabled
Library InstallationManual compilation and dependency resolution4 essential libraries pre-installed and tested
Path ConfigurationManual LUA_PATH and LUA_CPATH setupAutomatic environment configuration via /etc/profile.d
Development ToolsMust manually install GCC, Make, headersComplete 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​

  1. Get your instance's public IP address from the cloud console.
  2. Use your SSH client to connect:
    ssh ec2-user@[Your_Public_IP]
  3. 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

Expected output: Lua 5.4.4 Copyright (C) 1994-2022 Lua.org, PUC-Rio

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​

PathTypeDescription
/usr/bin/luaFileLua interpreter executable
/usr/bin/luacFileLua compiler (bytecode generator)
/usr/include/DirectoryLua C API headers (lua.h, lauxlib.h, lualib.h, etc.)
/usr/lib64/liblua-5.4.soFileLua shared library for C embedding
/usr/lib64/lua/5.4/DirectorySystem-level directory for native (.so) modules
/usr/share/lua/5.4/DirectorySystem-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​

PathTypeDescription
/usr/local/bin/luarocksFileLuaRocks package manager executable
/usr/local/bin/luarocks-adminFileLuaRocks repository administration tool
/usr/local/etc/luarocks/config-5.4.luaFileLuaRocks configuration file (modify for custom repositories or proxies)
/usr/local/lib/luarocks/rocks-5.4/DirectoryInstalled rocks metadata and manifests
/usr/local/share/lua/5.4/DirectoryLuaRocks-installed Lua source modules
/usr/local/lib/lua/5.4/DirectoryLuaRocks-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​

LibraryVersionPurpose
luasocket3.0.0TCP/UDP networking, HTTP client, SMTP, FTP protocols
luasec1.3.2SSL/TLS encryption for secure HTTPS connections
luafilesystem1.9.0Cross-platform file system operations (directory iteration, attributes, etc.)
lua-cjson2.1.0.10High-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:

  1. luasocket: Essential for any network programming. Provides HTTP client, TCP/UDP sockets, and common protocols.
  2. luasec: Adds SSL/TLS support to luasocket, enabling secure HTTPS connections (critical for modern web APIs).
  3. luafilesystem: Provides cross-platform file system operations that are not available in standard Lua.
  4. 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 PathPurpose
/usr/bin/luaLua interpreter executable
/usr/bin/luacLua compiler (bytecode generator)
/usr/include/lua*.hLua C API headers (for embedding or extension development)
/usr/lib64/liblua-5.4.soLua 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/luarocksLuaRocks package manager
/usr/local/etc/luarocks/config-5.4.luaLuaRocks 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.shSystem-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:

  1. 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')"
  2. 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
  3. 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:

  1. Using interpreted mode: Compile frequently-used modules to bytecode:

    luac -o module.luac module.lua
  2. Inefficient JSON library: Verify you're using lua-cjson (C-accelerated), not pure Lua JSON:

    lua -e "local cjson = require('cjson'); print(cjson._VERSION)"
  3. 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:

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

For support or questions, please contact the Easycloud team.