diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9d568f8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# SpaceAPI Server
+
+A Flask-based server implementation of the [SpaceAPI](https://spaceapi.io/) specification, designed to provide real-time status information about a hackerspace. This server allows you to expose your space's status through a standardized API endpoint and update it using a secure token-based authentication system.
+
+## Features
+
+- Compliant with SpaceAPI v14 and v15 specifications
+- Secure token-based authentication for state updates
+- Docker support for easy deployment
+- Real-time space status updates
+- Configurable space information (name, location, contact details, etc.)
+
+## Prerequisites
+
+- Docker (for containerized deployment)
+- Python 3.11+ (for local development)
+
+## Environment Variables
+
+The following environment variables need to be set:
+
+- `SPACEAPI_TOKEN`: A secret token used to authenticate state update requests
+- `FLASK_APP`: Set to `app.py` (automatically set in Docker)
+- `FLASK_ENV`: Set to `production` (automatically set in Docker)
+
+## Deployment with Docker
+
+1. Clone the repository:
+   ```bash
+   git clone <repository-url>
+   cd spaceapi-server
+   ```
+
+2. Create a `.env` file with your configuration:
+   ```bash
+   cp .env.example .env
+   # Edit .env and set your SPACEAPI_TOKEN
+   ```
+
+3. Build and run the Docker container:
+   ```bash
+   docker build -t spaceapi-server .
+   docker run -p 5000:5000 --env-file .env spaceapi-server
+   ```
+
+The server will be available at `http://localhost:5000`.
+
+## API Endpoints
+
+### GET /
+Returns the current space status in SpaceAPI format.
+
+### POST /state
+Updates the space status. Requires authentication using the `X-SpaceAPI-Token` header.
+
+Example request:
+```bash
+curl -X POST http://localhost:5000/state \
+  -H "Content-Type: application/json" \
+  -H "X-SpaceAPI-Token: your-token-here" \
+  -d '{"open": true}'
+```
+
+## Local Development
+
+1. Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Set up environment variables and run the server:
+   ```bash
+   export SPACEAPI_TOKEN=your-token-here
+   flask run
+   ```
+
+## License
+
+[Add your license information here] 
\ No newline at end of file