Deploy YaCy

Deploy and Host YaCy on Railway

Self-host YaCy to run a search engine you own end to end. YaCy is a free, GPL-licensed search engine in Java that does the whole job itself: it crawls the sites you point it at, parses what it finds — HTML, PDF, Office documents, RSS — indexes the text into an embedded Apache Solr, and serves a search interface with ranking, faceting and snippets over it. There is no third-party search API, no key to rotate and no per-query bill.

Deploy YaCy on Railway and this template gives you a single yacy service holding the web interface, the crawler and the Solr index, with a persistent volume at /opt/yacy_search_server/DATA for the index, crawl queues and configuration. The public domain routes to YaCy's own port, while the health check watches a separate endpoint that queries Solr directly, so a container that runs but cannot answer queries is reported unhealthy.

Getting Started with YaCy on Railway

Set YACY_ADMIN_PASSWORD when you deploy — at least 8 characters — then open the generated Railway URL. YaCy uses HTTP Digest authentication, so the browser shows a native login dialog: sign in as admin with the password you chose; there are no default credentials to change afterwards. The first useful action is a crawl: open Production → Crawler, paste a site URL and press Start New Crawl. The crawler monitor shows live queue depth, pages per minute, index size and a link-structure graph — the quickest way to confirm the deployment works. Once a few dozen pages are indexed, use the search box, or /yacysearch.html?query=your+terms, for ranked results with domain, author, filetype and language facets. Monitoring → Index Browser lists which paths were stored.

By default the whole portal, search included, sits behind that admin login. Set YACY_PUBLIC_SEARCH=true to publish the search pages to anonymous visitors while the administration pages stay protected.

About Hosting YaCy

Developed since 2003, YaCy is one of the few open-source projects shipping a complete search stack rather than one layer of it. Self-host it when you want search over content you choose, with no query quotas and no data leaving your infrastructure.

Key features:

• A polite crawler with robots.txt obedience, per-host delays, depth limits and scheduling
• Parsers for HTML, PDF, Office formats, archives and RSS, so a PDF becomes full text
• An embedded Apache Solr index with faceting, ranking profiles and a JSON/XML search API
• A search portal UI, plus OpenSearch and RSS output
• Blacklists, crawl profiles, an index browser and a re-crawl scheduler
• An optional peer-to-peer mode joining YaCy's public network

This template runs YaCy as a standalone portal: one service, one volume, no peer-to-peer exchange, which keeps the index yours and its size predictable. Jetty, the crawler, the parsers and Solr all live in one container.

Why Deploy YaCy on Railway

Railway removes the operational work around a Java search server.

• One-click deploy with the volume, ports and health check wired
• Persistent storage for the Solr index
• Automatic HTTPS on a generated domain, or bring your own
• Heap and thread pools sized from the container's limits, not the host's
• Vertical scaling from the dashboard as your index grows
• Logs, metrics and rollbacks without extra tooling

Common Use Cases

• Documentation and intranet search — crawl internal or vendor sites and give staff one search box
• A searchable PDF archive — full-text search over reports and papers
• Niche public search portals — a curated index of a topic or community
• Research and monitoring — scheduled re-crawls of sites you track, with an API for what changed

Dependencies for YaCy

• yacy — the only service. Built from gridalpha/yacy-railway, a thin layer over the official yacy/yacy_search_server:latest image that renders YaCy's configuration at boot, sizes the JVM from the container's limits and adds the health endpoint.
• A persistent volume at /opt/yacy_search_server/DATA — index, crawl queues, configuration and HTTP cache. Without it, every redeploy starts empty.

No database, cache or object storage is required: Solr is embedded and stores everything on that volume.

Environment Variables Reference

Deployment Dependencies

• Source repository: gridalpha/yacy-railway
• Upstream project: yacy/yacy_search_server
• Container image: yacy/yacy_search_server
• Documentation: yacy.net
• Runtime: Java 24 (Eclipse Temurin), Jetty 12, Apache Solr

Hardware Requirements for Self-Hosting YaCy

Crawling is the demanding phase; serving queries is cheap. The heap is derived from the container's memory limit, so raising the service's memory raises the JVM heap on the next deploy.

Self-Hosting YaCy with Docker

The official image runs YaCy in one command, given a volume so the index survives a restart:

docker run -d --name yacy -p 8090:8090 \
  -v yacy_data:/opt/yacy_search_server/DATA \
  yacy/yacy_search_server:latest

Then open http://localhost:8090 and sign in with the image's default credentials, admin / yacy, which you should change immediately under Administration → Use Case & Account. The Railway template removes that step: it computes the credential from YACY_ADMIN_PASSWORD before the server starts, so no default password is ever live.

To build from source instead, YaCy uses Apache Ant and a JDK:

git clone https://github.com/yacy/yacy_search_server.git
cd yacy_search_server
ant compile
./startYACY.sh -f

Configuration lives in DATA/SETTINGS/yacy.conf, which the server rewrites while running — edit it with the server stopped, or use the web interface.

Is YaCy Free?

YaCy is free and open source under the GPL — no paid tier, licence key or hosted plan, and every feature is in the same build. On Railway you pay only for infrastructure: one service plus the volume holding the index. The cost grows with how much you index and how hard you crawl.

YaCy vs Other Self-Hosted Search

SearXNG fits when you want private, aggregated results from existing engines. Pick YaCy when you need an index of your own.

FAQ

What is YaCy? An open-source search engine combining a web crawler, document parsers, an Apache Solr index and a search interface in one Java application.

What does this Railway template deploy? A single yacy service built from the official image, with a persistent volume for the Solr index, a public HTTPS domain, an administrator credential generated from your password, and a health check that queries the index.

Why does this template need a volume? The index, crawl queues and configuration are files on disk, and containers are replaced on every deploy — without a volume each redeploy would start empty.

How do I make my self-hosted YaCy search page public? Set YACY_PUBLIC_SEARCH=true and redeploy. Anonymous visitors can then search, while the administration pages stay behind the login.

Can I join the YaCy peer-to-peer network from this deployment? Yes. Set YACY_NETWORK_UNIT=defaults/yacy.network.freeworld.unit before the first boot and the peer joins the public network rather than running standalone. It applies on first boot only, and a peer-to-peer index grows on its own, so give it a larger volume.

How do I query my index from another application? /yacysearch.json?query=terms returns JSON, /yacysearch.rss returns RSS, and /solr/select takes standard Solr queries. Requests use the same authentication as the interface, so send the admin credential unless the search pages are published.