> How do I install SPX on my device? There are several ways to get the [[Documentation/Graphics Controller/Overview|SPX Graphics Controller]] up and running. Most users should start with the **official installation**, which comes pre-compiled and ready to use. Developers who want to customize or contribute can build SPX from the **source code** instead. --- ## Official Installation After receiving your SPX Graphics Controller, follow these steps to ensure a clean and working installation. > [!tip] For production environments, always use the official installer. Pre-compiled releases are more carefully tested than the source code in the repository. ### 1. Download Download the version best suited for your operating system. > [!TIP] Get the official SPX Graphics Controller from the [SPX Graphics website](https://spxgraphics.com/software). ### 2. Extract the Zip File After downloading the release zip, extract it. You will find a folder containing the application binary: - **macOS & Linux:** `spx-server` - **Windows:** `spx-server.exe` Make sure the executable/binary is in the same directory as the `ASSETS` and `DATAROOT` folders. ### 3. Installation & Running #### Linux ```bash chmod +x spx-server-linux-x64 ./spx-server-linux-x64 ``` Follow any prompts to complete configuration. After setup, the application will display your HOST-ID, which is required for licensing. #### macOS Open the folder in Finder. Right-click inside the folder and select **New Terminal at Folder**. Then run: ```bash ./spx-server ``` You will be prompted for user access configuration — select Yes or No. After setup, the application will display your HOST-ID, which is required for licensing. #### Windows Open the folder containing `spx-server-windows.exe`. Run the application by double-clicking it or from the Command Prompt: ```cmd spx-server-windows.exe ``` Follow the prompts to complete the user access configuration. Your HOST-ID will be displayed after setup for licensing purposes. ### 4. Notes - Keep your HOST-ID safe — it is required to activate your license. - All executables/binaries must be in the same directory as the `ASSETS` and `DATAROOT` folders. On first launch, SPX generates a [[Documentation/Server/Configurations|config.json]] file with default values along with `LOG` and `DATAROOT` folders in the installation directory. A browser window opens automatically with the SPX interface, typically at `http://127.0.0.1:5656`. See [[Guides/Getting Started/First Launch|First Launch]] for a walkthrough of the initial setup. ### Common Errors #### Port in use: If SPX fails to start with `Error: listen EADDRINUSE: address already in use`, another application is already using that port. Open `config.json` in a text editor, change the `general.port` value to a different port (e.g. `5657`), save, and relaunch. #### Bad CPU type in executable (M1/M2 Mac): On Apple Silicon Macs, you may see *"bad cpu type in executable"*. Fix this by running Terminal with Rosetta: right-click Terminal → Get Info → check **Open using Rosetta**, then launch SPX from that Terminal session. #### File not executable (Mac and Linux): On macOS and Linux, the operating system may not treat the downloaded file as an executable. Open a terminal, navigate to the extracted folder, and run: ```bash # Linux sudo chmod +x ./SPX_linux64 # macOS sudo chmod +x ./SPX_macos64 ``` #### macOS "App is damaged" error: Some Mac users encounter *"App is damaged and can't be opened. You should move it to the Trash."* This is caused by macOS adding an extended attribute to the file. Remove it with `xattr` in the Terminal: ```bash xattr -cr ./SPX_macos64 ``` #### macOS wrong folder issue: On some Mac systems, generated files may appear in the user's home directory instead of the application directory. If this happens, navigate to the installation folder in a Terminal first, or use the full path to the executable. --- ## SPX Launcher SPX Launcher is a desktop application for launching and managing SPX Graphics Controller directly from your desktop. - Start and stop the SPX server - View server status and logs - Quick access to the SPX web interface --- ## SPX Installer SPX Installer is a desktop application that provides a graphical interface for installing your SPX Graphics Controller. --- ## Source Code Installation The SPX source code is publicly available on [GitHub](https://github.com/TuomoKu/SPX-GC). Developers can clone the repository and run SPX directly using NodeJS. > [!warning] The source code in the repository is always in a **work in progress** state and features may or may not work. For production use, always prefer the official installer. ### Prerequisites - **Node.js** (v14 or later) - **npm** (comes with Node.js) - **Git** (for cloning the repository) ### Steps 1. Clone the repository: ```bash git clone https://github.com/TuomoKu/SPX-GC.git . ``` 2. Install dependencies: ```bash npm i ``` 3. Start the server: ```bash node server.js ``` For development mode with hot reloading, use: ```bash npm run dev ``` ### Running with PM2 For production deployments from source code, consider using the [PM2](https://pm2.keymetrics.io/) process manager. PM2 keeps SPX running in the background, restarts it automatically on crashes, and provides monitoring tools. ```bash npm start ``` You can also run several SPX instances simultaneously on different ports by using a PM2 `ecosystem.config.js` file. Each instance can have its own port and [[Documentation/Server/Configurations|configuration]]. > [!note] When running multiple instances, make sure each instance uses a unique `general.port` value in its [[Documentation/Server/Configurations|config.json]]. --- ## Read Next - [[Guides/Getting Started/First Launch|First Launch]] - What to expect on first startup - [[Documentation/Server/Configurations|Configurations]] - Server configuration options - [[Documentation/Server/License|License]] - License types and management - [[Documentation/Products/Overview|Products Overview]] - Compare SPX product tiers