Olivier/cursor-nixos-flake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation with comprehensive usage guide and improved update script

Browse Source
This commit is contained in:
thinktankmachine
2025-08-06 15:38:06 +10:00
parent 9d0bcd6aed
commit 035a280383
2 changed files with 392 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+259 -104
View File
@@ -1,165 +1,320 @@
# Cursor Flake
# Cursor NixOS Flake
A NixOS flake that provides a complete development environment with Cursor 1.3.9 (AI-first code editor) as an AppImage.
A NixOS flake that provides Cursor 1.3.9 (AI-first code editor) as an AppImage with enhanced compatibility for NixOS systems.
## Features
- **Cursor 1.3.9**: Latest version of the AI-first code editor
- **AppImage Support**: Full AppImage compatibility with proper desktop integration
- **Development Tools**: Complete development environment with Node.js, Python, Rust, and more
- **Enhanced AppImage Support**: Optimized for NixOS with proper library paths and environment setup
- **Easy Integration**: Can be used as a standalone system or integrated into existing NixOS flakes
- **Development Tools**: Complete development environment with modern tools
- **Modern Shell**: Zsh with Starship prompt and useful aliases
- **Desktop Environment**: GNOME with essential utilities
- **Git Integration**: Pre-configured Git with modern defaults
## Prerequisites
## Quick Start
- NixOS system with flakes enabled
- At least 8GB RAM recommended
- 20GB free disk space
## Installation
### 1. Clone the Repository
### Option 1: Use as a Standalone System
```bash
# Clone the repository
git clone https://github.com/thinktankmachine/cursor-nixos-flake
cd cursor-nixos-flake
```
### 2. Update the SHA256 Hash (if needed)
The current configuration uses the working Cursor 1.3.9 download URL. If you need to update to a newer version, run:
```bash
./update-cursor-hash.sh
```
This will automatically update the hash in `home.nix` with the correct value.
### 3. Customize Configuration
Edit the following files to match your system:
- `configuration.nix`: System-wide settings
- `home.nix`: User-specific settings (change username from "liam" to your username)
- `hardware-configuration.nix`: Hardware-specific settings (run `nixos-generate-config` on your target system)
### 4. Build and Switch
```bash
# Build the configuration
sudo nixos-rebuild build --flake .#cursor-system
# Switch to the new configuration
# Build and switch to the configuration
sudo nixos-rebuild switch --flake .#cursor-system
```
### 5. First Boot Setup
### Option 2: Integrate into Existing NixOS Flake
After the first boot:
Add to your `/etc/nixos/flake.nix`:
1. Log in as the configured user
2. Cursor will be available in the applications menu
3. You can also launch it from the terminal with `cursor`
```nix
{
inputs = {
# ... your existing inputs
cursor-flake = {
url = "github:thinktankmachine/cursor-nixos-flake";
inputs.nixpkgs.follows = "nixpkgs";
inputs.home-manager.follows = "home-manager";
};
};
outputs = { nixpkgs, home-manager, cursor-flake, ... }: {
nixosConfigurations.your-system = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
# ... your existing modules
{
home-manager.users.your-username = { pkgs, ... }: {
home.packages = with pkgs; [
# ... your existing packages
] ++ [
# Add Cursor from the flake
cursor-flake.packages.x86_64-linux.cursor
];
};
}
];
};
};
}
```
Then rebuild:
```bash
sudo nix flake update
sudo nixos-rebuild switch --flake .#your-system
```
## Usage
After installation, Cursor will be available:
- **Applications Menu**: Look for "Cursor" in your desktop environment
- **Terminal**: Run `cursor` from any terminal
- **Command Line**: Use `cursor --version` to verify installation
## Updating Cursor
When a new version of Cursor is released, follow these steps to update the flake:
### Step 1: Find the New Download URL
1. Go to [Cursor's download page](https://cursor.sh/)
2. Find the Linux AppImage download link
3. Copy the URL (it will look like: `https://downloads.cursor.com/production/[hash]/linux/x64/Cursor-[version]-x86_64.AppImage`)
### Step 2: Update the Flake
1. **Update the URL in `home.nix`**:
```nix
# Find this section in home.nix
cursorAppImage = pkgs.writeShellScriptBin "cursor" ''
# ... environment setup ...
# Run the AppImage with appimage-run
exec ${pkgs.appimage-run}/bin/appimage-run ${pkgs.fetchurl {
url = "https://downloads.cursor.com/production/[NEW_HASH]/linux/x64/Cursor-[NEW_VERSION]-x86_64.AppImage";
sha256 = "OLD_HASH_HERE"; # This will be updated in the next step
}} "$@"
'';
```
2. **Update the SHA256 hash**:
```bash
# Run the update script (it will fetch the new URL and update the hash)
./update-cursor-hash.sh
```
3. **Test the build**:
```bash
# Test that the flake builds correctly
nix build .#packages.x86_64-linux.cursor
```
4. **Update your system**:
```bash
# If using standalone system
sudo nixos-rebuild switch --flake .#cursor-system
# If integrated into main system
cd /etc/nixos
sudo nix flake update
sudo nixos-rebuild switch --flake .#your-system
```
### Step 3: Verify the Update
```bash
# Check the version
cursor --version
# Launch Cursor to ensure it works
cursor
```
### Step 4: Commit and Push (Optional)
```bash
# Commit the changes
git add .
git commit -m "Update Cursor to version [NEW_VERSION]"
git push origin main
```
## Configuration
### Cursor Settings
### Customizing the Cursor Wrapper
The flake includes pre-configured Cursor settings in `~/.config/Cursor/User/settings.json`:
The Cursor AppImage wrapper in `home.nix` includes enhanced compatibility settings:
- Modern font (JetBrains Mono with ligatures)
- Dark theme
- Optimized editor settings
- Cursor AI features enabled
```nix
cursorAppImage = pkgs.writeShellScriptBin "cursor" ''
# Set up environment for better AppImage compatibility
export APPDIR=""
export ARGV0=""
export OWD=""
# Ensure proper library paths
export LD_LIBRARY_PATH="${pkgs.lib.makeLibraryPath [
pkgs.glib
pkgs.gtk3
pkgs.cairo
pkgs.pango
pkgs.atk
pkgs.gdk-pixbuf
pkgs.xorg.libX11
pkgs.xorg.libXcomposite
pkgs.xorg.libXcursor
pkgs.xorg.libXext
pkgs.xorg.libXfixes
pkgs.xorg.libXi
pkgs.xorg.libXrandr
pkgs.xorg.libXrender
pkgs.xorg.libXtst
pkgs.nss
pkgs.nspr
pkgs.dbus
pkgs.at-spi2-atk
pkgs.at-spi2-core
pkgs.mesa
pkgs.alsa-lib
]}:$LD_LIBRARY_PATH"
# Run the AppImage with appimage-run
exec ${pkgs.appimage-run}/bin/appimage-run ${pkgs.fetchurl {
url = "https://downloads.cursor.com/production/[hash]/linux/x64/Cursor-[version]-x86_64.AppImage";
sha256 = "[hash]";
}} "$@"
'';
```
### Development Environment
### Adding Additional Packages
The flake includes:
To add more development tools, edit `home.nix`:
- **Languages**: Node.js 20, Python 3, Rust
- **Tools**: Git, ripgrep, fd, bat, exa, fzf, tmux
- **Shell**: Zsh with Starship prompt
- **Terminal**: Alacritty
### Customization
To customize the configuration:
1. **Add packages**: Edit `home.nix` and add to `home.packages`
2. **Change shell**: Modify the shell configuration in `home.nix`
3. **Update Cursor settings**: Edit the settings in `home.nix`
4. **System packages**: Add to `environment.systemPackages` in `configuration.nix`
```nix
home.packages = with pkgs; [
# Existing packages...
# Add your packages here
nodejs_20
python3
rustc
cargo
# ... more packages
];
```
## Troubleshooting
### AppImage Issues
### Common Issues
If Cursor doesn't run properly:
#### 1. AppImage Won't Run
1. Check if AppImage support is enabled:
```bash
ls /proc/sys/fs/binfmt_misc/
```
**Symptoms**: `bwrap: Can't chdir to /etc/nixos: No such file or directory`
2. Reinstall AppImage support:
```bash
sudo nixos-rebuild switch --flake .#cursor-system
```
**Solution**: Run Cursor from your home directory, not from system directories:
```bash
cd ~
cursor
```
### Permission Issues
#### 2. Keymapping Errors
If you encounter permission issues:
**Symptoms**: `Error: Cannot find module './build/Debug/keymapping'`
1. Ensure the user is in the correct groups:
```bash
groups
```
**Solution**: These are cosmetic errors and don't prevent Cursor from working. The enhanced wrapper should reduce these errors.
2. Add user to additional groups if needed in `configuration.nix`
#### 3. Library Loading Issues
### Update Cursor
**Symptoms**: Various library-related errors
To update to a newer version of Cursor:
**Solution**: The enhanced wrapper includes all necessary libraries. If issues persist, try:
```bash
# Rebuild the system
sudo nixos-rebuild switch --flake .#your-system
1. Update the version number in `home.nix`
2. Update the download URL if needed
3. Update the SHA256 hash
4. Rebuild the system
# Clear AppImage cache
rm -rf ~/.cache/appimage-run/*
```
#### 4. Git Authentication Issues
**Symptoms**: `fatal: Authentication failed`
**Solution**: Ensure your remote uses SSH:
```bash
git remote set-url origin git@github.com:username/repo.git
```
### Testing the Flake
You can test the flake without affecting your system:
```bash
# Build the VM image
nix build .#nixosConfigurations.cursor-system.config.system.build.vm
# Run the VM
./result/bin/run-cursor-system-vm
```
## File Structure
```
cursor-flake/
├── flake.nix # Main flake definition
├── flake.nix # Main flake definition with outputs
├── configuration.nix # NixOS system configuration
├── home.nix # Home Manager user configuration
├── home.nix # Home Manager configuration with Cursor wrapper
├── hardware-configuration.nix # Hardware-specific settings
└── README.md # This file
├── update-cursor-hash.sh # Script to update Cursor hash
├── test-configuration.nix # Minimal test configuration
├── test-home.nix # Minimal test home configuration
└── README.md # This documentation
```
## Development
### Adding Features
1. **New packages**: Add to `home.packages` in `home.nix`
2. **System changes**: Modify `configuration.nix`
3. **User settings**: Update `home.nix` configuration
### Testing Changes
```bash
# Test the flake syntax
nix flake check
# Test building the package
nix build .#packages.x86_64-linux.cursor
# Test the full system
nix build .#nixosConfigurations.cursor-system.config.system.build.vm
```
## Contributing
1. Fork the repository
2. Create a feature branch
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Test the configuration
5. Submit a pull request
4. Test thoroughly: `nix flake check`
5. Commit: `git commit -m "Add feature description"`
6. Push: `git push origin feature-name`
7. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
This project is licensed under the MIT License.
## Support
For issues and questions:
1. Check the troubleshooting section
2. Search existing issues
3. Create a new issue with detailed information
- **Issues**: [GitHub Issues](https://github.com/thinktankmachine/cursor-nixos-flake/issues)
- **Discussions**: [GitHub Discussions](https://github.com/thinktankmachine/cursor-nixos-flake/discussions)
## Acknowledgments
- Cursor team for the excellent AI-first editor
- NixOS community for the amazing package management system
- Home Manager for user configuration management
- [Cursor](https://cursor.sh/) team for the excellent AI-first editor
- [NixOS](https://nixos.org/) community for the amazing package management system
- [Home Manager](https://github.com/nix-community/home-manager) for user configuration management