AtmosphericX - Installation (v7.1.2)

Posted Jul 7, 2025

By Kiyomi , StarflightVR

7 min read

If you wish to watch the installation video, you can do so by clicking the play button above. The video will walk you through the installation process step by step. If you prefer to read the guide, please continue reading below.

Introduction

Thank you for your interest in AtmosphericX!

This guide is designed to walk you through the process of setting up AtmosphericX from start to finish. It includes clear instructions for installing all required dependencies, configuring your environment, and ensuring everything is ready for development or deployment. Whether you are a first-time user or an experienced developer, this guide aims to make the setup process as smooth and straightforward as possible. If you run into any issues, have questions, or just want to connect with the community, we encourage you to join our official Discord server.

This install guide is only for Windows and Linux users. If you are using macOS, please refer to the Linux installation guide as the steps are very similar. If you need additional help, please join our Discord server.

Prerequisites

Software	Version	Purpose
Node.js	v18.0.0 or higher	JavaScript runtime environment
Git	Latest	Required for auto-updating and cloning the repository
NPM	Comes with Node.js	Package manager for JavaScript
Linux (Optional)	If Ubuntu (22.04+) or Debian (11+)	For running the project on a Linux server
Windows (Optional)	If Windows 10 or later	For running the project on a Windows server

Windows (10-11) Installation Steps

  
# This script is designed for Windows 10 and later. If you wish to install manually, please refer to the manual installation steps below.
curl -L -o Git-2.50.0.2-64-bit.exe https://github.com/git-for-windows/git/releases/download/v2.50.0.windows.2/Git-2.50.0.2-64-bit.exe
curl -L -o node-v22.17.0-x64.msi https://nodejs.org/dist/v22.17.0/node-v22.17.0-x64.msi
start /wait Git-2.50.0.2-64-bit.exe
start /wait node-v22.17.0-x64.msi

set "PATH=%ProgramFiles%\Git\cmd;%PATH%"
set "PATH=%ProgramFiles%\nodejs;%PATH%"
npm --version

del Git-2.50.0.2-64-bit.exe & 
del node-v22.17.0-x64.msi

git --version
git clone https://github.com/k3yomi/AtmosphericX

cd AtmosphericX
start /wait install.sh &
start /wait run.sh

Note: This script is designed for Windows 10 and later. It will install Git and Node.js, clone the AtmosphericX repository, and run the installation script. Make sure to run this in a command prompt with administrative privileges.

Manual Installation Steps

Installing Node.js and NPM:
- Download the latest version of Node.js from the official website.
- Run the installer and follow the prompts to install Node.js and NPM.
Installing Git:
- Download Git from the official website.
- Run the installer and follow the prompts to install Git.
Cloning the AtmosphericX Repository:
- Open a command prompt and run the following command:
  1 git clone https://github.com/k3yomi/AtmosphericX
Navigate to the AtmosphericX Directory:
- Change to the AtmosphericX directory:
  1 cd AtmosphericX

Installing Dependencies:

Run the following command to install the required dependencies:

  
  # Two methods are available for installing dependencies
  start /wait install.sh # Recommended for general use
  cd project_atmospheric_x & npm install . # Optional for "advanced" users

Running the Application:

Start the application by running:

  
   # Two commands can be used to run the application...
   start /wait run.sh # Recommended for general use
   cd project_atmospheric_x & node index.js # Optional for "advanced" users

Linux Installation Steps

Note: This guide is for Ubuntu 20.04+ (Debian 11+) users. If you are using a different Linux distribution, the steps may vary slightly. Please refer to your distribution’s documentation for specific instructions.

Installing Node.js and NPM:
- Open a terminal and run the following commands to install Node.js and NPM:
  1 2 sudo apt update sudo apt install nodejs npm git -y
Cloning the AtmosphericX Repository:
- Run the following command to clone the repository:
  1 git clone https://github.com/k3yomi/AtmosphericX
Navigating to the AtmosphericX Directory:
- Change to the AtmosphericX directory:
  1 cd AtmosphericX

Installing Dependencies:

Run the following command to install the required dependencies:

  
   # Two methods are available for installing dependencies...
   bash install.sh # Recommended for general use
   cd project_atmospheric_x & npm install . # Optional for "advanced" users

Run the Application:

Start the application by running:

  
   # Two commands can be used to run the application...
   bash run.sh # Recommended for general use
   cd project_atmospheric_x & node index.js # Optional for "advanced" users

Installation Issues & Guidance

Accessing the Dashboard and Configuring Your Instance

By default, the dashboard will be accessible at http://localhost:80 or http://<your-server-ip>:80 if you are running it on a server. You may also type localhost to access the dashboard. If you wish to configure your instance, you can do so by editing the configurations.json in the project directory. If you wish to learn more about the configurations, please refer to the AtmosphericX Configurations Guide.

Note: To access the dashboard with default credentials, use the following:
Username: root
Password: root It’s recommended to change these credentials after the first login for security purposes. You can do this in the dashboard settings. If you wish to allow guests, make sure the value guests in the hosting section is set to true.

If you wish to create an account, you can do so by clicking “Create an account?” in the portal (login) page. You will be prompted to enter a unique username, and a password. Please note that the username must be unique. To enable the account to be used in your instance, you will need to use the command suite in the terminal. See AtmosphericX Command Reference for more information on how to use the command suite.

Updating AtmosphericX

To update AtmosphericX for future releases, you can either manually install the entire project again or use the update script provided in the project directory. To use the update script, run the following command in the AtmosphericX directory:

bash update.sh # If you are on Windows, you can simply double-click the update.sh file

The update script will automatically pull the latest version of the project from Github and do a new install of your configuration (if necessary). If a new configuration is installed, you will have a backup of your previous configuration in the configurations.bak directory. Please do note that the update script will NOT backup your entire project, it’s up to you to backup your project if you wish to do so.

CharacterAI Integration (Chatbot) [DEPRECATED]

The project includes a basic integration with CharacterAI, allowing you to create a custom chatbot that can answer questions about the weather (to a certain extent) and provide information about the current weather conditions by context in the alert description.

There are some limitations to this integration, one being hallucinations. Hallucinations are when the chatbot provides information that is not accurate or does not exist. This is a common issue with AI chatbots, and it is important to be aware of this when using the integration.

Windows is only supported for the integration itself as the Linux version of the integration has issues while installing even the latest versions of all prerequisites. If you wish to use the integration, please select “Y” when prompted during the installation process. If you do not wish to use the integration, simply select “N” and the integration will not be installed. Please keep in mind, enabling the integration via the configurations while it’s not installed will cause the project to error out and not run properly

If you wish to set this up, please see: AtmosphericX CharacterAI Integration Guide.

Warning: The CharacterAI integration is experimental and may not work as expected. It is recommended to wait for further updates and integrations with other AI models. This is solely for fun and should not be relied upon for critical weather information.

Troubleshooting

If you encounter any issues during the installation or running of AtmosphericX, please check the following:

Ensure that you have installed all the required dependencies.
Check the logs in the /storage/logs file for any error messages.
Check the configurations in the configurations.json file to ensure that it’s valid and properly configured. (See: JSON Validator)
Manually run the project with node index.js to see if there are any errors that are not being displayed in the terminal.
If you are still having issues, please join our Discord server and ask for help in the bug-reports channel.

AtmosphericX, Installation Guide

This post is licensed under CC BY 4.0 by the author.